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PREFACE 



This publication is planned for use as a 
reference book by the PL/I user. It is not 
intended to be a tutorial publication, but 
is designed for the reader who already has 
a knowledge of the language and who 
requires a source of reference material. 

It is divided into two parts. Part I 
contains discussions of concepts of the 
language. Part II contains detailed rules 
and syntactic descriptions. 

Although implementation information is 
included, the book is not a complete 
description of any implementation 
environment. In general, it contains 
information needed in writing a program; it 
does not contain all of the information 
required to execute a program. For further 
information on executing a program refer to 
the publication: IBM System/360 Time 
Sharing System: PL/I Programmer's Guide , 
Form GC2 8-2 04 9. 

The features discussed in this 
publication correspond to those implemented 
in tne fifth version of the PL/I (F) 
Compiler in Release 18 of IBM System/360 
Operating System. 
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The following publication contains a 
description of the IBM System/360 Time 
Sharing System: 
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IMPLEMENTATION CONSIDERATIONS Implementation features identified by 
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SECTION 1: BASIC CHARACTERISTICS OF PL/I 



The modularity of PL/ I, the ease with 
which subsets can be defined to meet dif- 
ferent needs, becomes apparent when one 
examines the different features of the lan- 
guage. Such modularity is one of the most 
important characteristics of PL/I. 

This chapter contains brief discussions 
of most of the basic features to provide an 
overall description of the language. Each 
is treated in more detail in subsequent 
sections. 



EtACHINE INDEPENDENCE 

No language can be completely machine 
independent, but PL/I is much less machine 
dependent than most commonly used program- 
ming languages. The methods used to 
achieve this show in the form of restric- 
tions in the language. The roost obvious 
example is that data with different charac- 
teristics cannot in general share the same 
storage; to equate a floating-point number 
with a certain number of alphabetic charac- 
ters would be to make assumptions about the 
representation of these data items which 
would not be true for all machines. 

It is recognized that the price entailed 
by machine independence may sometimes be 
too high. In the interest of efficiency, 
certain features such as the UNSPEC built- 
in function and record-oriented data trans- 
mission, do permit a degree of machine 
dependence. 



PROGRAM STRUCTURE 

A PL/I program consists of one or more 
blocks of statements called procedures. A 
procedure may be thought of as a subrou- 
tine. Procedures may invoke other proce- 
dures, and these procedures or subroutines 
may either be compiled separately, or may 
be nested within the calling procedure and 
compiled with it. Each procedure may con- 
tain declarations that define names and 
control allocation of storage. 

The rules defining the use of proce- 
dures, communication between procedires, 
the meaning of names, and allocation of 
storage are fundamental to the proper un- 
derstanding of PL/I at any level bu*. the 
most elementary. These rules give the user 
considerable control over the c*-gree of 
interaction between subroutines* They per- 
mit flexible communication and storage 
allocation, at the same time allowing the 



definition of names and allocation of 
storage for private use within a procedure. 

By giving the user freedom to determine 
the degree to which a subroutine is self- 
contained, PL/I makes it possible to write 
procedures which can freely be used in 
ether environments, while still allowing 
interaction in procedures where interaction 
is desirable. 



DATA TYPES AND DATA DESCRIPTION 

The characteristic of PL/I that most 
contributes to the range of applications 
for which it can be used is the variety of 
data types that can be represented and 
manipulated. PL/I deals with arithmetic 
data, string data (bit and character), and 
program control data, such as labels. 
Arithmetic data may be represented in a 
variety of ways; it can be binary or deci- 
mal, fixed- point or floating-point, real or 
complex, and its precision may be 
specified. 

PL/I provides features to perform arith- 
metic operations, operations for compari- 
sons, logical manipulation of bit strings, 
and operations and functions for assem- 
bling, scanning, and subdividing character 
strings. 

The compiler must be able to determine, 
for every name used in a program, the com- 
plete set of attributes associated with 
that name. The user may specify these 
attributes explicitly by means of a DECLARE 
statement, the compiler may determine all 
or some of the attributes by context, or 
the attributes may be assumed by default. 



DEFAULT ASSUMPTIONS 

An important feature of PL/I is its 
default philosophy. If all the attributes 
associated with a name, or all the options 
permitted in a statement, are not specified 
by the user, attributes or options may be 
assigned by the compiler. This default 
action has two main consequences. First, 
it reduces the amount of declaration and 
other program writing required; second, it 
makes it possible to teach and use subsets 
of the language for which the user need not 
know all possible alternatives, or even 
that alternatives exist. 

Since defaults are based on assumptions 
about the intent of the user, errors or 
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omissions may be overlooked, and incorrect 
attributes may be assigned by default. To 
reduce the chance of this, the compiler 
optionally provides an attribute listing, 
which can be used to check the names in the 
program and the attributes associated with 
them . 



STORAGE ALLOCATION 

PL/I goes beyond most other languages in 
the flexibility of storage allocation that 
it provides. Dynamic storage allocation is 
comparatively difficult for an assembler- 
language user to handle for himself; yet it 
is automatically provided in PL/I. There 
are four different storage classes: AUTO- 
MATIC, STATIC, CONTROLLED, and BASED. In 
general, the default storage class in PL/I 
is AUTOMATIC. This class of storage is 
allocated whenever the block in which the 
variables are declared is activated. At 
that time the bounds of arrays and the 
lengths of strings are calculated. AUTO- 
MATIC storage is freed and is available for 
reuse whenever control leaves the block in 
which the storage is allocated. 

Storage also may be declared STATIC, in 
which case it is allocated when the program 
is loaded; it may be declared CONTROLLED, 
in which case it is explicitly controlled 
by the user with ALLOCATE and FREE state- 
ments, independent of the invocation of 
blocks; or it may be declared BASED, which 
gives the user an even higher degree of 
control. 

The existence of several storage classes 
enables the user to determine for himself 
the speed, storage space, or programming 
economy that he needs for each application. 
The cost of a particular facility will 
depend upon the implementation, but it will 
usually be true that the more dynamic the 
storage allocation, the greater the over- 
head in execution time. 



When such mixed expr 
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The results of the evaluation of expres- 
sions are assigned to variables by means of 
the assignment statement. An example of an 
assignment statement is: 

X = A + B * C; 

This means: evaluate the expression on the 
right and store the result in X . If the 
attributes of X differ from the attributes 
cf the result of the expression, conversion 
will again be performed. 



LATA C0L1ECTI0NS 

PL/I permits the user many ways of 
describing and operating on collections of 
data, or data aggregates. Arrays are 
collections of data elements, all of the 
same type, collected into lists or tables 
of one or more dimensions. Structures are 
hierarchical collections of data, not 
necessarily all of the same type- Each 
level of the hierarchy may contain other 
structures of deeper levels. The deepest 
levels of the hierarchy represent elemen- 
tary data items or arrays. 

An element of an array may be a struc- 
ture; similarly, any level of a structure 
may be an array. Operations can be speci- 
fied for arrays, structures, or parts of 
arrays or structures. For example: 

A = B + C; 

In this assignment statement, A f B, and C 
could be arrays or structures. 



EXPRESSIONS 

Calculations in PL/I are specified by 
expressions. An expression has a meaning 
in PL/I that is similar to that of elemen- 
tary algebra. For example: 

A + B * C 

This specifies multiplication of th * value 
of B by the value of C and adding the value 
of A to the result. PI/I places few re- 
strictions on the kinds of data that can be 
used in an expression. For example, it is 
conceivable, though unlikely, that A could 
be a floating-point number, B a fixed-point 
number, and C a character string. 



INPUT AND OUTPUT 

Facilities for input and output allow 
the user to choose between factors such as 
simplicity, machine independence, and effi- 
ciency. There are two broad classes of 
input/ output in PL/I: stream-oriented and 
record-oriented . 

Stream-oriented input/output is almost 
completely machine independent. On input, 
data items are selected one by one from 
what is assumed to be a continuous stream 
of characters that are converted to inter- 
nal form and assigned to variables speci- 
fied in a list. , Similarly, on output, data 



items are converted one by one to external 
character form and are added to a conceptu- 
ally continuous stream of characters. 
Within the class of stream input/output , 
the user can choose different levels of 
control over the way data items are edited 
and selected from or added to the stream. 

For printing, the output stream may be 
considered to be divided into lines and 
pages. An output stream file may be 
declared to be a print file with a speci- 
fied line size and page size. The user has 
facilities to detect the end of a page and 
to specify the beginning of a line or a 
page. These facilities may be used in sub- 
routines that can be developed into a 
report generating system suitable for a 
particular installation or application. 

Record-oriented input/output is machine 
dependent. It deals with collections of 
data, called records, and transmits these a 
record at a time without any data conver- 
sion; the external representation is an 
exact copy of the internal representation. 
Because the aggregate is treated as a 
whole, and because no conversion is per- 
formed, this form of input/output is poten- 
tially more efficient than stream-oriented 
input/output, although the actual efficien- 
cy of each class will, of course, depend on 
the implementation. 



tion of program text. For example, it 
might specify the inclusion or deletion of 
debugging statements. 

Since a simple but powerful part of the 
PL/I language is available for compile-time 
activity, the generation, or replacement 
and deletion, of text can become more elab- 
orate, and more subtle transformations can 
be performed. Such transformations might 
then be considered to be installation- 
defined extensions to the language. 



INTERRUP TION ACT IVITIES 

Computing systems provide facilities for 
interrupting the execution of a program 
whenever an exceptional condition arises. 
Further, they allow the program to deal 
with the exceptional condition and to 
return to the point at which the interrup- 
tion occurred. 

PI/ I provides facilities for detecting a 
variety of exceptional conditions. It 
allows the user to specify, by means of a 
condition prefix, whether certain interrup- 
tions will or will not occur if the condi- 
tion should arise. And, by use of an ON 
statement, he can specify the action to be 
taken when an interruption does occur. 



Stream-oriented input and output usually 
sacrifices efficiency for ease of handling. 
Each data item is transmitted separately 
and is examined to determine if data con- 
version is required. Record-oriented input 
and output, on the other hand, provides 
faster transmission by transmitting data as 
entire records, without conversion. 



COMPILE-TIME OPERATIONS 

Most programming is concerned only with 
operations upon data. PL/I permits a 
compile-time level of operation, in which 
preprocessor statements specify operations 
upon the text of the source program itself. 
The simplest, and perhaps the commonest 
preprocessor statement is %INCLUDE (in gen- 
eral, preprocessor statements are preceded 
by a percent sign) . This statement causes 
text to be inserted into the program, 
replacing the ^INCLUDE statement itself. A 
typical use could be to copy declarations 
from an installation's standard set of 
definitions into the program. 

Another function provided by compile- 
time facilities is the selective coupila- 



MULTIT ASKING 

In TSS/360, the concept of multitasking 

is inherent in the structure of the system; 
there are extensive multitasking facilities 
in the TSS/360 command system. In this 
implementation of the compiler, no initia- 
tion of tasks will be permitted from within 
a PL/I executable program. The user can 
start an independent task in TSS/360 by 
several different methods. There is no way 
for these tasks to communicate within the 
PL/I code. (Refer to IBM System/360 Time 
Sharing System: Command System User's 
Guide , Order No. GC28-2001.) 

The effect, then, is that although mul- 
titasking statements are accepted by the 
compiler, the current implementation cannot 
honor them and upon encountering a tasking 
statement will terminate execution. 



Note ; If a program contains a CALL state- 
ment with a multitasking option (TASK, 
EVENT, or PRIORITY) , the entire program is 
unacceptable for TSS/360 execution. 
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SECTION 2: PROGRAM ELEMENTS 



There are few restrictions in the format 
of PL/I statements. Consequently, programs 
can be written without consideration of 
special coding forms or checking to see 
that each statement begins in a specific 
column. As long as each statement is ter- 
minated by a semicolon, the format is com- 
pletely free. Each statement may begin in 
the next column or position after the pre- 
vious statement, or any number of blanks 
may intervene. 



CHARACTER SETS 

One of two character sets may be used to 
write a source program; either a 60- 
eharacter set or a 4 8-character set. For a 
given external procedure, the choice 
between the two sets is optional. 



60-CHARACTER SET 

The 60-character set is composed of 
digits, special characters, and alphabetic 

characters . 

There are 29 alphabetic characters 
beginning with the currency symbol ($), the 
number sign (#), and the commercial "at" 
sign (a) f which precede the 26 letters of 
the English alphabet in the IBM System/360 
collating sequence in Extended Binary- 
Coded-Decimal Interchange Code (EBCDIC). 
For use with languages other than English, 
the first three alphabetic characters can 
be used to cause printing of letters that 
are not included in the standard English 
alphabet. 

There are ten digits. The decimal 
digits are the digits through 9. A 
binary digit is either a or a 1. 

There are 21 special characters. They 
are as follows: 



Name Character 

Colon : 

"Not" symbol -, 

"And" symbol £ 

"Or" symbol | 

"Greater than" symbol > 

"Less than" symbol < 

Ereak character 1 _ 

Question mark ? 

Special characters are combined to cre- 
ate other symbols. For example, <= means 
"less than or equal to," -|= means "net 
equal to." The combination ** denotes 
exponentiation (X**2 means X 2 ) . Blanks are 
not permitted in such composite symbols. 

An alphameric character is either an 
alphabetic character or a digit, but not a 
special character. 

Note : The question mark, at present, has 
no specific use in the language, even 
though it is included in the 60-character 
set. 



48-CHARACTER SET 

The 48-character set is composed of U8 
characters of the 60-character set. In all 
but four cases, the characters of the 
reduced set can be combined to represent 
the missing characters from the larger set. 
For example, the percent symbol (%) is not 
included in the 48-character set, but a 
double slash (//) can be used to represent 
it. The four characters that are not du- 
plicated are the commercial "at" sign, the 
number sign, the break character, and the 
question mark. 

The restrictions and changes for this 
character set are described in Part II, 
Section 2, "Character Sets with EBCDIC and 
Card-Punch Codes." 



Name 



Character 



Blank 

Equal sign or assignment symbol = 

Plus sign + 
Minus sign 

Asterisk or multiply symbol * 

Slash or divide symbol / 

Left parenthesis ( 

Right parenthesis ) 

Comma , 
Point or period 

| Apostrophe * 

Percent symbol % 

Semicolon ; 



USING THE CHARACTER SET 

All the elements that make up a PL/I 
program are constructed from the PL/I 
character sets. There are two exceptions: 
character-string constants and comments may 
contain any character permitted by a par- 
ticular machine configuration. 



^The break character is the same as the 
typewriter underline character. It can be 
used with a name, such as GROSS_PAY, to 
improve readability. 



Certain characters perform specific 
functions in a PL/ I program. For example, 
many characters function as operators. 

There are four types of operators: 
arithmetic, comparison, bit- string, and 
string. 

The arithmetic operators are: 



denoting addition or prefix plus 
denoting subtraction or prefix 

minus 
denoting multiplication 
denoting division 
denoting exponentiation 



* 
/ 



The comparison operators ares 



> 
>= 



<= 
< 



denoting "greater than" 
denoting "not greater than" 
denoting "greater than or 

equal to" 
denoting "equal to" 
denoting "not equal to" 
denoting "less than or equal to" 
denoting "less than" 
denoting "not less than" 



The bit-string operators are: 






denoting 
denoting 
denoting 



"not" 

"and" 
"or" 



Tne string operator is: 

| | denoting concatenation 

Figure 1 shows some of the functions of 
other special characters. 

Identifiers 

In a PL/I program, names or labels are 
given to data, files, statements, and entry 
points of different program areas. In 
creating a name or label, a user must 
observe the syntactic rules for creating an 
identifier. 

An identifier is a single alphabetic 
character or a string of alphameric and 
break characters, not contained in a com- 
ment or constant, and preceded and followed 
by a blank or some other delimiter? the 
initial character of the string must be 
alphabetic. For System/360 implementation, 
the length must not exceed 31 characters. 

Language keywords also are identifiers. 
A keyword is an identifier that, when used 
in proper context, has a specific meaning 
to the compiler. A keyword can specify 
such things as the action to be taken, the 
nature of data, the purpose of a name. For 
example, READ, DECIMAL, and ENDFILE are 
keywords. Some keywords can be abbre- 
viated. A complete list of keywords and 



_ T T - 

| Character | 



Name 



I- +- 

comma 

period 

semicolon 

assignment 
symbol 

colon 

blank 

apostrophe 
parentheses 



arrow 



percent 

symbol 

(. _. 



C ) 

-> 

% 



Use I 

. + . „ .- „ .„_ i 

Separates elements of a list 

Indicates decimal point or binary point; connects elements 
of a qualified name 

Terminates statements 

Indicates assignment of values 1 

Connects prefixes to statements; can be used in specifica- 
tion for bounds of an array 

Separates elements of a ?;Latement 

Encloses string constants and picture specification 

Enclose lists; specify information associated with various 
keywords; in conjunction with operators and operands, 
delimit portions of a computational expression 

Denotes pointer qualification 

Indicates statements to be executed by the compiler 
preproc assor 



j. x_- .— . . . ._ . 



| *Note that the 

L 

Figure 1. Some 



— _ i 

character = c>. be used as an equal sign and as an assignment symbol. | 

. „_ — .__ . „— .___. ._. .. . . — _j 

Functions of Special Characters 
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their abbreviations is contained in Part 
II, Section 3, "Keywords and Keyword 
Abbreviations . m 

Note: PL/I keywords are not reserved 
words. They are recognized as keywords by 
the compiler only when they appear in their 
proper context. In other contexts they may 
be used as user-defined identifiers. 

No identifier can exceed 31 characters 
I in length; for the TSS/360 PL/I compiler, 
some identifiers, as discussed in later 
chapters, cannot exceed seven characters in 
length. This limitation is placed upon 
certain names, called external names, that 
| may be referred to by the time -sharing sys- 
tem or by more than one separately compiled 
procedure. If an external name contains 
more than seven characters, it is truncated 
by che compiler , which concatenates the 
fiist four characters with the last three 
characters. 

Examples of identifiers that could be 
used for names or labels; 



FIJLE2 
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for documentation purposes, 
be punched into the same cards 
either inserted between 

in the middle of them. 



LOOP 3 



RATE OF PAY 



The general format of a comment is: 

/* character™ string */ 

The character pair /* indicates the 
beginning of a comment. The same character 
pair reversed, */, indicates its end. No 
blanks or other characters can separate the 
two characters of either composite pair; 
the slash and the asterisk must be irrmedi- 
ately adjacent. The comment itself may 
contain any characters except the */ combi- 
nation, which would be interpreted as ter- 
minating the comment. 

Example: 

/* THIS WHOLE SENTENCE COULD BE 
INSERTED AS A COMMENT */ 

Any characters permitted for a particu- 
lar machine configuration may be used in 
comments . 
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EASIC PROGRAM STRUCTURE 



The Use o f Blank s 

Blanks may be used freely throughout a 
PL/I program. They may or may not surround 
operators and most other delimiters. In 
general, any number of blanks may appear 
wherever one blank is allowed, such as 
between words in a statement. 



A PL/I program is constructed from basic 
program elements called statements . There 
are two types of statements: simple and 
compound. These statements make up larger 
program elements called groups and blocks. 



SIMPLE AND COMPOUND STATEMENTS 



One or more blanks must be used to 
separate identifiers and constants that are 
not separated by some other delimiter or by 
a comment. However, identifiers, constants 
(except character-string constants) and 
composite operators (for example, 1 =) can- 
not contain blanks. 

Other cases that require or permit 
blanks are noted in the text where the fea- 
ture of the language is discussed. Some 
examples of the use of blanks are: 

AB+BC is equivalent to AB + BC 
TABLE(IO) is equivalent to TABLE (10) 
FIRST, SECOND is equivalent to FIRST, SECOND 
ATOB is not equivalent to A TO B 

Comments 

Comments are permitted wherever blanks 
are allowed in a program, except within 



There are three types of simple state- 
ments: keyword, assignment, and null, each 
cf which contains a statement body that is 
terminated by a semicolon. 

A keywor d s tatement has a keyword to 
indicate the function of the statement; the 
statement body is the remainder of the 
statement. 

The assignment statement contains the 
assignment symbol (=) and does not have a 
keyword. 

The null statement consists only of a 
semicolon and indicates no operation; the 
semicolon is the statement body. 

Examples of simple statements are: 



GO TO LOOP 3; 



(GO TO is a keyword; the 
blank between GO and TO 
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A = B + C; 



is optional. The state- 
ment body is LOOP_3;.) 

(assignment statement) 



A compound statement is a steitement that 
contains one or more other statements as a 
part of its statement body. There are two 
compound statements: the IF statement and 
the ON statement. The final statement of a 
compound statement is a simple statement 
that is terminated by a semicolon. Hence, 
the compound statement is terminated by 
this semicolon. The IF statement can con- 
tain two simple statements as shown in the 
following example: 

IF A>B THEN A = B+C; ELSE GO TO 
LOOP_3; 

This example can also be written as 
follows : 

IF A>B 

THEN A=B+C; 

ELSE GO TO LOOP_3; 

Following are examples of the ON 
statement: 

ON OVERFLOW GO TO OVFIX; 
ON UNDERFLOW; 

The contained statement in the second 
example is the null statement represented 
by a semicolon only; it indicates that no 
action is to be taken when an UNDERFLOW 
interruption occurs. 

Statement Prefixes 

Both simple and compound statements may 
have one or more prefixes. There are two 
types of prefixes; the label prefix and the 
condition prefix. 

A label prefix identifies a statement so 
that it can be referred to at some other 
point in the program. A label prefix is an 
identifier that precedes the statement and 
is connected to the statement by a colon. 
Any statement may have one or more labels. 
If more than one are specified, they may be 
used interchangeably to refer to that 
statement. 

A condition prefix specifies whether or 
not interruptions are to result from the 
occurrence of the named conditions. Condi- 
tion names are language keywords, each of 
which represents an exceptional condition 
that might arise during execution of a pro- 
gram. Examples are OVERFLOW and SIZE. The 
OVERFLOW condition arises when the exponent 
of a floating-point number exceeds the 
maximum allowed (representing a maximum 
value of about 10 75 ) . The SIZE condition 
arises when a value is assigned to a vari- 



able with loss of high-order digits or 
bits. 

A condition name in a condition prefix 
iray be preceded by the word NO to indicate 
that, effectively, no interruption is to 
cccur if the condition arises. If NO is 
used, there can be no intervening blank 
between the NO and the condition naire. 

A condition prefix consists of a list of 
cne or more condition names, separated by 
commas and enclosed in parentheses. One or 
irore condition prefixes may be attached to 
a statement, and each parenthesized list 
irust be followed by a colon. Condition 
prefixes precede the entire statement, 
including any possible label prefixes for 
the statement. For example: 



CSIZE, NCOVERFLOW) : COMPUTE: A 



B * C ** D; 



The single condition prefix indicates that 
an interruption is to occur if the SIZE 
condition arises during execution of the 
assignment statement, but that no interrup- 
tion is to occur if the OVERFLOW condition 
arises. Note that the condition prefix 
precedes the label prefix COMPUTE. 

Since intervening blanks between a pre- 
fix and its associated statement are 
ignored, it is often convenient to punch 
the condition prefix into a separate card 
that precedes the card into which the 
statement is punched. Thus, after debug- 
ging, the prefix can be easily removed. 
For example: 

(NOCONVERSION) : 

( SI ZE , NCOVERFLOW) : 

COMPUTE: A = B * C ** D; 

Note that there are two condition prefixes. 
The first specifies that no interruption is 
to occur if an invalid character is encoun- 
tered during an attempted data conversion. 

Condition prefixes are discussed in Part 
I, Section 13, "Exceptional Condition 
Handling and Program Checkout. * 



GROUPS AND BLOCKS 

A group is a sequence of statements 
headed by a DO statement and terminated by 
a corresponding END statement. It Is used 
for control purposes. A group also may be 
called a DO-group. 

A block is a sequence of statements that 
defines an area of a program. It is used 
to delimit the scope of a name and for con- 
trol purposes. A program may consist of 
cne or more blocks. Every statement must 
appear within a block. There are two kinds 
of blocks : begin blocks and procedure 
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blocks , A begin block is delimited by a block must be invoked by execution of a 
BEGIN statement and an END statement. A statement in another block. The first pro- 
procedure block is delimited by a PROCEDURE cedure in a program to be executed is 
statement and an END statement. Every invoked automatically by the system. For 
begin block must be contained within some System/360 implementations, this first pro- 
procedure block. cedure must be identified by specifying 

OPTIONS (MAIN) in the PROCEDURE statement. 
Execution passes sequentially into and 
out of a begin block. However, a procedure 
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SECTION 3: DATA ELEMENTS 



Data is generally defined as a represen- 
tation of information or of value. 

In PL/I, reference to a data itera f 
arithmetic or string, is made by using 
either a variable or a constant (the terms 
are not exactly the same as in general 
mathematical usage) . 

A variable is a symbolic name having a 
value that may change during execution of a 
program. 

A constant (which is not a symbolic 
name) has a value that cannot change. 

The following statement has both 
variables and constants: 

AREA = RAD1US**2*3.1416; 

AREA and RADIUS are variables; the numbers 
2 and 3.1416 are constants. The value of 
RADIUS is a data item, and the result of 
the computation will be a data item that 
will be assigned as the value of AREA. The 
number 3.1416 in the statement is itself 
the data item; the characters 3.1416 also 
are written to refer to the data item. 

If the number 3.1416 is to be used in 
more than one place in the program, it may 
be convenient to represent it as a variable 
to which the value 3.1416 has teen 
assigned. Thus, the above statement could 
be written as: 

PI = 3.1416; 

AREA = RADIUS**2*PI; 

In this statement, only the digit 2 is a 
constant. 

In preparing a PL/I program, the user 
must be familiar with the types of data 
that are permitted, the ways in which data 
can be organized, and the methods by which 
data can be referred to. The following 
paragraphs discuss these features. 



DATA TYPES 

The types of data that may be used in a 
PL/I program fall into two categories: 
problem data and program control data. 
Problem data is used to represent vilues to 
be processed by a program. It consists of 
two data types, arithmetic and string. 
Program control data is used to control the 
execution of a program. Program control 



data consists of the following types: 
label, event, task, locator, and area. 

A constant does more than state a value; 
it demonstrates various characteristics of 
the data item. For example, 3.1416 shows 
that the data type is arithmetic and that 
the data item is a decimal number of five 
digits and that four of these digits are to 
the right of the decimal point. 



The characte 
not immediately 
Since these cha 
butes , must be 
expressions may 
attributes of a 
statement. The 
each data type 
this chapter, 
each attribute 
9, "Attributes 



PROBLEM DATA 



ristics of a variable are 

apparent in the name, 
racteristics, called attri- 
known, certain keywords and 
be used to specify the 
variable in a DECLARE 
attributes used to describe 
are discussed briefly in 
A complete discussion of 
appears in Part II, Section 



The types of problem data are arithmetic 
and string. 



ARITHMETIC DATA 

An item of arithmetic data is one with a 
numeric value. Arithmetic data items have 
the characteristics of base, scale, preci- 
sion, and mode. The characteristics of 
data items represented by an arithmetic 
variable are specified by attributes 
declared for the name, or assumed by 
default. 

The bas e of an arithmetic data item is 
either decimal or binary. 

Tne scale of an arithmetic data iteir is 
either fixed-point or floating-point. A 
fixed-^oint data item is a number in which 
the position of the decimal or binary point 
is specified* either by its appearance in a 
constant or by a scale factor declared for 
a variable. A floating-point data item is 
a number followed by an optionally signed 
exponent. The exponent specifies the 
assumed position of the decimal or binary 
point, relative to the position in which it 
appears. 

The precision of an arithmetic data item 
is the number of digits the data item may 
contain, in the case of fixed-point, or the 
nrinircum number of significant digits 
(excluding the exponent) to be maintained, 
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in the case of floating-point. For fixed- 
point data items, precision can also speci- 
fy the assumed position of the decimal or 
binary point, relative to the rightmost 
digit of the number. 



Whenever a data item is 
fixed-point variable, the 
sion is maintained- The a 
aligned on the decimal or 
Leading zeros are inserted 
item contains fewer intege 
declared; trailing zeros a 
contains fewer fractional 
error may occur if the ass 
tains too many integer dig 
on the right may occur if 
many fractional digits - 



assigned to a 
declared preci- 
ssigned item is 
binary point. 

if the assigned 
r digits than 
re inserted if it 
digits. A SIZE 
igned item con- 
its; truncation 
it contains too 



The mode of an arithmetic data item is 
either real or complex. A real data item 
xs a number that expresses a real value. A 
complex data item is a pair of numbers: 
the first is real and the second is 
imaginary. For a variable representing 
complex data items, the base, scale, and 
precision of the two parts must be 
identical . 

Base, scale, and mode of arithmetic 
variables are specified by keywords; preci- 
sion is specified by parenthesized decimal 
integer constants. The precision of arith- 
metic constants is discussed in greater 
detail below, under the heading "Precision 
of Arithmetic Constants. " 

In the following sections, the real 
arithmetic data types discussed are decimal 
fixed-point, sterling fixed-point, binary 
fixed-point, decimal floating-point, and 
binary floating-point. Any of these, 
except sterling fixed-point, can be used as 
the real part of a complex data item. The 
imaginary part of a complex number is dis- 
cussed in "Complex Arithmetic Data," in 
this section. 

Complex arithmetic variables must be 
explicitly declared with the COMPLEX attri- 
bute. Real arithmetic variables may be 
explicitly declared to have the REAL attri- 
bute, but it is not necessary to do so, 
since any arithmetic variable is assumed to 
be real unless it is explicitly declared 
complex. 



Decimal Fixed-Point Data 

A decimal fixed-point constant consists 
of one or more decimal digits with an 
optional decimal point. If no decimal 
point appears, the point is assumed to be 
immediately to the right of the rightmost 
digit. In most uses, a sign may optionally 
precede a decimal fixed- point constant. 



Examples of decimal fixed-point con- 
stants as written in a program are: 

3.1416 

455.3 

732 

003 

5280 

.0012 

The keyword attributes for declaring 
decimal fixed-point variables are DECIMAL 
and FIXED. Precision is stated by two dec- 
imal integers, separated by a comma and 
enclosed in parentheses. The first, which 
must be unsigned, specifies the total num- 
ber of digits; the second, the scale fac- 
tor, may be signed and specifies the number 
of digits to the right of the decimal 
point. If the variable is to represent 
integers, the scale factor and its preced- 
ing comma can be omitted. The attributes 
may appear in any order, but the precision 
specification must follow either DECIMAL or 
FIXED (or REAL or COMPLEX). 

Following are examples of declarations 
of decimal fixed-point variables: 

DECLARE A FIXED DECIMAL (5,4); 
DECLARE B FIXED (6,0) DECIMAL; 
DECLARE C FIXED (7,-2) DECIMAL; 

The first DECLARE statement specifies that 
the identifier A is to represent decimal 
fixed-point items of not more than five 
digits, four of which are to be treated as 
fractional, that is, to the right of the 
assumed decimal point. Any item assigned 
to A will be converted to decimal fixed- 
point and aligned on the decimal point. 
The second DECLARE statement specifies that 
B is to represent integers of no more than 
6 digits. Note that the comma and the zero 
are unnecessary; it could have been speci- 
fied B FIXED DECIMAL C6). The third 
DECLARE statement specifies a negative 
scale factor of -2; this means that the 
assumed decimal point is two places to the 
right of the rightmost digit of the item. 

The maximum number of decimal digits 
allowed for System/360 implementations is 
15. Default precision, assumed when nc 
specification is made, is (5,0). The 
internal coded arithmetic form of decimal 
fixed- point data is packed decimal. Packed 
decimal is stored two digits to the byte, 
with a sign indication in the rightmost 
four bits of the rightmost byte. Conse- 
quently, a decimal fixed-point data item is 
always stored as an odd number of digits, 
even though the declaration of the variable 
may specify the number of digits (p) as an 
even number. When the declaration speci- 
fies an even number of digits, the extra 
digit place is in the high-order position, 
and it participates in any operations per- 
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formed upon the data item, such as in a 
comparison operation. Any arithmetic over- 
flow or assignment into an extra high-order 
digit place can be detected only if the 
SIZE condition is enabled. 

Sterling Fixed-Point Data 

PL/I has a facility for handling con- 
stants stated in terms of sterling currency 
value. The data may be written in a pro- 
gram with pounds, shillings, and pence 
fields, each separated by a period. Such 
data is converted and maintained internally 
as a decimal fixed-point number represent- 
ing the equivalent in pence. A sterling 
data constant ends with the letter L, 
representing the pounds symbol. All three 
fields (pounds, shillings, and pence) must 
be present in a sterling constant. Note 
that the the maximum number of digits 
allowed in the pounds field of a sterling 
constant is 13. The pence field is one or 
more decimal digits with an optional deci- 
mal point (the integer part must be less 
than 12 and cannot be omitted, and the 
fractional part must not exceed 13 minus 
the number of digits in the pounds field) . 

Examples of sterling fixed-point con- 
stants as written in a program are: 

101.13.8L 
1.10.0L 
0.0.2.5L 
2.14. 6L 

The third example represents twopence- 
halfpenny. The last example represents two 
pounds, four shillings, and six pence. It 
is converted and stored internally as 534 
(pence) . 

There are no keyword attributes for 
declaring sterling variables, but a vari- 
able can be declared with a sterling pic- 
ture, or sterling values may be expressed 
in pence as decimal fixed-point data. The 
precision of a sterling constant is the 
precision of its value expressed in pence. 

Binary Fixed-Point Data 

A binary fixed-point constant consists 
of one or more binary digits with an 
optional binary point, followed immediately 
by the letter B, with no intervening blank. 
In most uses, a sign may optionally precede 
the constant. 

Examples of binary fixed-point constants 
as written in a program are: 

10110B 
11111B 
101B 
111.01B 
1011. 111B 



The keyword attributes for declaring 
binary fixed-point variables are BINARY and 
FIXED. Precision is specified by two deci- 
mal integer constants, enclosed in paren- 
theses, to represent the maximum number of 
binary digits and the number of digits to 
the right of the binary point, respective- 
ly. If the variable is to represent inte- 
gers , the second digit and the coirira can be 
emitted. The attributes can appear in any 
order, but the precision specification must 
follow either BINARY or FIXED (or REAL or 
COMPLEX) . 

Following is an example of declaration 
cf a binary fixed-point variable: 

DECLARE FACTOR BINARY FIXED (20,2); 

FACTOR is declared to be a variable that 
can represent arithmetic data items as 
large as 20 binary digits, two of which are 
fractional. The decimal equivalent of that 
value range is from -262,144.00 through 
+262,143.75. 

The maximum number of binary digits 
allowed for System/360 implementations is 
31. Default precision is (15,0). The 
internal coded arithmetic form of binary 
fixed-point data is a fixed-point binary 
fullword or halfword. (A fullword is 31 
bits plus a sign bit; a halfword is 15 bits 
plus a sign fcit.) Any binary fixed-point 
variable of precision less than 16 is 
always stored as 15 digits, even though the 
declaration of the variable may specify 
fewer digits; any binary fixed-point vari- 
able of precision greater than 15 (or any 
binary fixed-point constant, regardless of 
precision) is always stored as 31 digits. 
The declared number of digits are consid- 
ered to be in the low-order positions, but 
the extra high-order digits participate in 
any operations performed upon the data 
item. Any arithmetic overflow into such 
extra high-order digit positions can be 
detected only if the SIZE condition is 
enabled. 

An identifier for which no declaration 
is made is assumed to be a binary fixed- 
point variable, with default precision, if 
its first letter is any of the letters I 
through N. 



Decimal Floating-Point Data 

A decimal floating-point constant is 
written as a field of decimal digits fol- 
lowed by the letter E, followed by an 
optionally signed decimal integer exponent. 
The first field of digits may contain a 
decimal point. The entire constant may be 
preceded by a plus or minus sign. Examples 
of decimal floating-point constants as 
written in a program are: 
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15E-23 

15E23 

4E-3 

48333E65 

438E0 

3141593E-6 

.003141593E3 

The last two examples represent the same 
value. 



power of two. The field of binary digits 
nay contain a binary point- A binary 
floating-point constant may be preceded by 
a plus or minus sign. Examples of binary 

floating-point constants as written in a 
program are?: 

101101E5B 

101.101E2B 

11101E-28B 



The keyword attributes for declaring 
decimal floating-point variables are DECI- 
MAL and FLOAT. Precision is stated by a 
decimal integer constant enclosed in paren- 
theses. It specifies the minimum number of 
significant digits to be maintained. If an 
item assigned to a variable has a field 
width larger than the declared precision of 
the variable, truncation may occur on the 
right. The least significant digit is the 
first that is lost. Attributes may appear 
in any order, but the precision specifica- 
tion must follow either DECIMAL or FLOAT 
(or REAL or COMPLEX) . 

Following is an example of declaration 
of a decimal floating-point variable: 

DECLARE LIGHT_YEARS DECIMAL FLOAT (5); 

This statement specifies that LIGHT JYEARS 
is to represent decimal floating-point data 
items with an accuracy of at least five 
significant digits. 

The maximum precision allowed for deci- 
mal floating-point data items for System/ 
360 implementations is (16); the exponent 
cannot exceed two digits. A value range of 
approximately 10- 78 to 10 75 can be ex- 
pressed by a decimal floating-point data 
item. Default precision is (6). The 
internal coded arithmetic form of decimal 
floating-point data is normalized hexadeci- 
mal floating-point, with the point assumed 
to the left of the first hexadecimal digit. 
If the declared precision is less than or 
equal to (6), short floating-point form is 
used; if the declared precision is greater 
than (6), long floating-point form is used. 

An identifier for which no declaration 
is made is assumed to be a decimal 
floating-point variable if its first letter 
is any of the letters A through H f O 
through Z # or one of the alphabetic exten- 
ders, $ r #, a. 



Binary Floating-Point Data 

A binary floating-point constant con- 
sists of a field of binary digits followed 
by the letter E, followed by an optionally 
signed decimal integer exponent followed by 
the letter B. The exponent is a string of 
decimal digits and specifies an integral 



The keyword attributes for declaring 
binary floating-point variables are EINARY 
and FLOAT. Precision is expressed as a 
decimal integer constant, enclosed in 
parentheses, to specify the minimum number 
of significant digits to be maintained. 
The attributes can appear in any order, but 
the precision specification must follow 
either BINARY or FLOAT (or REAL or COM- 
PLEX). Following is an example of declara- 
tion of a binary floating-point variable: 

DECLARE S BINARY FLOAT (16); 

This specifies that the identifier S is to 
represent binary floating-point data items 
with 16 digits in the binary field. 

The maximum precision allowed for binary 
floating-point data items for System/360 
implementations is (53); default precision 
is (21). The exponent cannot exceed three 
decimal digits. A value range of approxim- 
ately 2- 26 ° to 2 2S2 can be expressed by a 
binary floating-point data item. The 
internal coded arithmetic form of binary 
floating-point data is normalized hexadeci- 
mal floating-point. If the declared preci- 
sion is less than or equal to (21) f short 
floating-point form is used; if the 
declared precision is greater than (21) , 
long floating-point form is used. 

Complex Arithmetic Data 

In the complex mode, an arithmetic data 
item is considered to consist of two parts, 
the first a real part and the second a 
signed imaginary part. There are no com- 
plex constants in PL/I. The effect is 
obtained by writing a real constant and an 
imaginary constant. 

An imaginary constant is written as a 
real constant of any type (except sterling 
fixed-point) immediately followed by the 
letter I. 

Examples of imaginary constants as writ- 
ten in a program are: 

271 

3.968E10I 
11011. 01BI 

Each of these is considered to have a real 

part of zero. Although complex constants 
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cannot be written with a nonzero real part, 
PL/I provides the facility to express such 
values in the following form: 



real-constant { + | -} imaginary-constant 

Thus a complex value could be written as 
38+271. 

The keyword attribute for declaring a 
complex variable is COMPLEX. A complex 
variable can have any of the attributes 
valid for the different types of real 
arithmetic data. Each of the base, scale, 
and precision attributes applies to both 
fields . 

Unless a variable is explicitly declared 
to have the COMPLEX attribute, it is 
assumed to represent real data items. 



Numeric Character Data 

A numeric character data item (also 
known as a numeric field data item) is the 
value of a variable that has been declared 
with the PICTURE attribute and a numeric 
picture specification. The data item is 
the character representation of a decimal 
fixed-point or floating-point value. 

A numeric picture specification 
describes a character string to which only 
data that has, or can be converted to, an 
arithmetic value is to be assigned. A nu- 
meric picture specification cannot contain 
either of the picture characters A or X, 
which are used for non-numeric picture- 
character strings. The basic form of a nu- 
meric picture specification is one or more 
occurrences of the digit-specif ying picture 
character 9 and an optional occurrence of 
the picture character V, to indicate the 
assumed location of a decimal point. The 
picture specification must be enclosed in 
apostrophes. For example: 

•999V99* 

This numeric picture specification 
describes a data item consisting of up to 
five decimal digits in character form, with 
a decimal point assumed to precede the 
rightmost two digits. 

Repetition factors may be used in numer- 
ic picture specifications. A repetition 
factor is a decimal integer constant, en- 
closed in parentheses, that indicates the 
number or repetitions of the immediately 
following picture character. For example, 
the following picture specification would 
result in the same descriptit » as the 
example shown above: 

• C3)9V(2>9 i 



The format for declaring a numeric 
character variable is: 



DECLARE identifier PICTURE 

' numeric-picture-specif icat ion 1 ; 

For example: 

DECLARE PRICE PICTURE ' 999V99 f ; 

This specifies that any value assigned to 
PRICE is to be maintained as a character 
string of five decimal digits, with an 
assumed decimal point preceding the right- 
most two digits. Data assigned to PRICE 
will be aligned on the assumed point in the 
same way that point alignment is maintained 
for fixed-point decimal data. 

The numeric picture specificaticn can 
specify all of the arithmetic attributes of 
data in much the same way that they are 
specified by the appearance of a constant. 
Only decimal numeric data can be repre- 
sented by picture character. Complex data 
can be declared by specifying the COMPLEX 
attribute along with a single picture spec- 
ification that describes either a fixed- 
point or a floating-point data item. 

It is important to note that, although 
numeric character data has arithmetic 
attributes, it is not stored in coded 
arithmetic form. In System/360 implementa- 
tions, numeric character data is stored in 
zoned decimal format; before it can be used 
in arithmetic computations, it must be con- 
verted either to packed decimal or to hexa- 
decimal floating-point format. Such con- 
versions are done automatically, but they 
require extra execution time. 

Although numeric character data is m 
character form, like character strings, and 
although it is aligned on the deciiral point 
like coded arithmetic data, it is processed 
differently from the way either coded 
arithmetic items or character strings are 
processed. Editing characters can be spe- 
cified for insertion into a numeric 
character data item, and such characters 
are actually stored within the data item. 
Consequently, when the item is printed or 
treated as a character string, the editing 
characters are included in the assignment. 
If, however, a numeric character item is 
assigned to another numeric character or 
arithmetic variable, the editing characters 
will not be included in the assignment; 
cnly the actual digits and the location of 
the assumed decimal point are assigned- 

Consider the following example: 

DECLARE PRICE PICTURE , $99V.99 t , 
COST CHARACTER (6), 
VALUE FIXED DECIMAL (6,2); 
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PRICE = 12.28; 
COST = * $12. 28' ; 

In the picture specif 
currency symbol C$) a 
{.) are editing char 
stored as characters 
They are not, however 
luetic value. After e 
assignment statement, 
character representat 
can be considered ide 
printed, they would p. 
They do not, however, 
same. For example: 

VALUE = PRICE; 
COST = PRICE; 
VALUE = COST; 

PRICE = COST; 



After the first two assignment state- 
ments are executed, the value of VALUE 
would be 0012.28 and the value of COST 
would be f $12.28*. In the assignment of 
PRICE to VALUE r the currency symbol and the 
decimal point are considered to be editing 
characters, and they are not part of the 
assignment; the arithmetic value of PRICE 
is converted to internal coded arithmetic 
torn,. In the assignment of PRICE to COST, 
however, the assignment is to a character 
stiing, and the editing characters of a nu- 
meric picture specification always parti- 
cipate? in such an assignment. No conver- 
sion is necessary because PRICE is stored 
in character form. 

The third and fourth assignment state- 
ments would cause errors. The value of 
COST cannot be assigned to VALUE because 
the currency symbol in the string makes it 
invalid as an arithmetic constant. The 
value of COST cannot be assigned to PRICE 
for exa ctly the same reason - Only values 
that are of arithmetic type, or that can be 
converted to arithmetic type, can be 
assigned to a variable declared with a nu- 
meric picture specification. 

Note: Although the decimal point can be an 
editing character or an actual character in 
a character string, it will not cause an 
error in converting to arithmetic form, 
since its appearance is valid in an arith- 
metic constant. The same would be true of 
a valid plus or minus sign, since arithme- 
tic constants can be preceded by signs. 

Other editing characters, including zero 
suppression characters, drifting charac- 
ters, and insertion characters, can be used 
in numeric picture specifications. For 
complete discussions of picture characters, 
see Part II, Section 4, "Picture Specifica- 
tion Characters" and the discussion of the 
PICTURE attribute in Part II, Section 9, 
"Attributes. w 



Precision of Arithmetic Constan ts 

For purposes of expression evaluation, 
an apparent precision is defined for real 

arithmetic constants: 

Real fixed-point constants have a preci- 
sion Cp,q> , where p is the total number of 
digits in the constant and q is the number 
of digits specified to the right of the 
decimal or binary point. 

The precision of a sterling constant is 
equivalent to the precision of its corre- 
sponding value in fixed-point pence. This 
value is determined as follows: multiply 
the value of the pounds field by 240; add 
the value of the shillings field multiplied 
by 12; add the value of the pence field. 
The precision of the result Cwith leading 
zeros removed) is the precision of the cor- 
responding sterling constant. 

The precision of a floating-point con- 
stant is (p) r where p is the number of 
digits of the constant left of the E. 

Examples : 

3.14 has precision (3,2) 
0.012E5 has precision (4) 
0.9.0.5L has precision (4,1) 
0000001B has precision (7,0) 



STRING DATA 

A string is a contiguous sequence of 
characters (or binary digits) that is 
treated as a single data item. The length 
of the string is the number of characters 
(or binary digits) it contains. 

There are two types of strings: 
character strings and bit strings. 

Character-String Data 

A character string can include any 
digit, letter f or special character recog- 
nized as a character by the particular 
machine configuration. Any blank included 
in a character string is an integral 
character and is included in the count of 
length. A comment that is inserted within 
a character string will not be recognized 
as a comment. The comment, as well as the 
comment delimiters (/* and */) , will be 
considered to be part of the character- 
string data. 

Character-string constants, when written 
in a program, roust be enclosed in apostro- 
phes. If an apostrophe is a character in a 
string, it must be written as two apostro- 
phes with no intervening blank. The length 
of a character string is the number of 
characters between the enclosing apostro- 
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phes. If two apostrophes are used within 
the string to represent a single apos- 
trophe, they are counted as a single 
character. 

A null character-string constant is 
written in a program as two apostrophes 
with no intervening blank. 



Examples of character-string constants 
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The keyword attribute for declaring a 
character-string variable is CHARACTER. 
Length is declared by an expression or a 
decimal integer constant, enclosed in 
parentheses, which specifies the number of 
characters in the string. The length spec- 
ification must follow the keyword CHARACTER 
For example: 

DECLARE NAME CHARACTER (15); 
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Character-string variables may also be 
declared to have the VARYING attribute, as 
follows: 

DECLARE NAME CHARACTER (15) VARYING; 

This DECLARE statement specifies that the 
identifier NAME is to be used to represent 
varying-length character-string data iteros 
with a maximum length of 15. The actual 
length attribute for NAME at any particular 



Character-string data in System/360 
implementations is maintained internally in 
character format, that is, each character 
cccupies one byte of storage. The maximum 
length allowed for variables declared with 
the CHARACTER attribute is 32,767. The 
maximum length allowed for a character- 
string constant after application of repe- 
tition factors varies according to the 
amount of storage available to the compil- 
er, but it never will be less than 1,007. 
The minimum length for a character string 
is zero. 

Character-str ing variables also can be 
declared using the PICTURE attribute of thn 
form: 

PICTURE ' character-picture-speci f icat ion" 
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DECLARE PART NO PICTURE • AA9999X999 • ; 

This DECIARE statement specifies that the 
identifier PART_NO will represent 
character-string data items consisting of 
two alphabetic characters, four numeric 
characters, one character that may be any 
character, and three numeric characters. 

Repetition factors are used in picture 
specifications differently from the way 
they are used in string constants. Repeti- 
tion factors must be placed inside the 
apostrophes. The repetition factor speci- 
fies repetition of the immediately follow- 
ing picture character. For example, the 
above picture specification could be 
written: 
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• (2>A(**)9X(3>9 f 

The maximum length allowed for a picture 
specification is the same as that allowed 
for character-string constants, as dis- 
cussed above. 

Note that, for character picture speci- 
fications, the picture character 9 speci- 
fies a digit or a blank , while, for numeric 
picture specifications, the same character 
specifies only a digit . 



Bit-string Data 

A bit-string constant is written in a 
program as a series of binary digits en- 
closed in apostrophes and followed immedi- 
ately by the letter B. 

A null bit-string constant is written in 
a program as two apostrophes with no inter- 
vening blank, followed immediately by the 

letter B. 

Examples of bit-string constants as 
written in a program are: 

•l'B 

f lllllOlOHOOO^B 

(6*4) 'O'B 

• 'B 

The parenthesized number in the third 
example is a repetition factor which speci- 
fies that the following series of digits is 
to be repeated the specified number of 
times. The example shown would result in a 
string of 64 binary zeros. 

A bit-string variable is declared with 
the BIT keyword attribute. Length is spec- 
ified by an expression or a decimal integer 
constant, enclosed in parentheses, to spec- 
ify the number of binary digits in the 
string. The letter B is not included in 
the length specification since it is not 
part of the string. The length specifica- 
tion must follow the keyword BIT. Follow- 
ing is an example of declaration of a bit- 
string variable: 

DECLARE SYMPTOMS BIT t64); 

Like character strings, bit strings are 
assigned to variables from left to right. 
If a string is longer than the length 
declared for the variable, the rightmost 
digits are truncated; if shorter, padding, 
on the right, is with zeros. 

A bit-string variable may be given the 
VARYING attribute to indicate it is to be 
used to represent varying- length bit 
strings. Its application is the same as 
that described for character-string 
variables in the preceding section. 



With System/360 implementations, bit 
strings are stored eight bits to a byte. 
The maximum length allowed for a bit-string 
variable with the TSS/360 PL/I compiler is 
32,767 bits. The maximum length allowed 
for a bit-string constant after application 
of repetition factors depends upon the 
amount of storage available to the compil- 
er, but it will never be less than 8,056 
(1,007 bytes). The minimum length for a 
bit string is zero. 



PROGRAM CONTROL DATA 

The types of program control data are 
label, event, task, locator, and area. 



LABEL DATA 

A label data item is a label constant or 
the value of a label variable. 

A label constant is an identifier writ- 
ten as a prefix to a statement so that, 
during execution, program control can be 
transferred to that statement through a 
reference to its label. A colon connects 
the label to the statement. 

ABCDE: DISTANCE = RATE*TIME; 

In this example, ABCDE is the statement 
label. The statement can be executed ei- 
ther by normal seguential execution of 
instructions or by transferring control to 
this statement from some other point in the 
program by means of a GO TO statement. 

As used above, ABCDE can be classified 
further as a statement- label constant. A 
statement-label variable iii an identiiici 
that refers to statement-label constants. 
Consider the following example: 

LBL_A: statement ; 



LBL __B: statement; 



LBL_X = LBL_A; 



GO TO LBL X; 



LBL_A and LBL__B are statement- label con- 
stants because they are prefixed to state- 
ments. LBL_X is a statement-label vari- 
able. By assigning LBL_A to LBL_X, the 
statement GO TO LBL_X causes a transfer to 
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the LBL__A statement. Elsewhere, the pro- 
gram may contain a statement assigning 
LBL_B to LBL__X. Then, any reference to 
LBL_X would be the same as a reference to 
LBL_B. This value of LBL_X is retained 
until another value is assigned to it. 

A statement-label variable must be 
declared with the LABEL attribute, as 
follows; 

DECLARE LBL X LABEL ; 



EVENT DATA 

Event variables are designed to coordi- 
nate the concurrent execution of a number 
of procedures in a multiprogramming 
environment, or to allow a degree of over- 
lap between a record-oriented input/output 
operation and the execution of other state- 
ments in the procedure that originated the 
operation. Since multitasking is not sup- 
ported in TSS/360, event variables used in 
a multiprogramming context do not have as 
much significance as in the IBK- System/360 
Operating System. 

A variable is given the EVENT attribute 
by its appearance in an EVENT option or a 
WAIT statement, or by explicit declaration, 
as in the following example: 

DECLARE ENDEVT EVENT; 

For detailed information, see "The EVENT 
Option" in Part I, Section 10, "Record- 
Oriented Transmission." 



TASK DATA 

Task variables are designed to control 
the relative priorities of different PL/I 
tasks (i.e., concurrent separate execution 
of procedures). Since in TSS/360, the cur- 
rent implementation does not support mul- 
tiple PL/I tasks, task variables have no 
significance. 



LOCATOR DATA 

There are two types of locator data: 
pointer and offset. 

The value of a pointer variable is ef- 
fectively an address of a location in 
storage, and so it can be used to qualify a 
reference to a variable that may hive been 
allocated storage in several different 
locations, all of which are immediately 
accessible. Since based storage if so 
allocated, reference to a based variable 
must be qualified in some way; *ith the 
TSS/360 compiler, this qualification must 
be provided by a pointer variable. 



The value of an offset variable speci- 
fies a location relative to the start of a 
reserved area of storage and remains valid 
when the address of the area itself 
changes. 

Locator variables can be declared as in 
the following example: 

DECLARE HEADPTR POINTER, 

FIRST OFFSET (AREA1); 

In this example, AREA1 is the name of the 
reserved area of storage that will contain 
the location specified by FIRST. 

A variable can also be given the POINTER 
attribute by its appearance in the BASED 
attribute, by its appearance on the left- 
hand side of a pointer qualification sym- 
bol, or by its appearance in a SET option. 

For detailed information, see Part I, 
Section 14, "Based Variables and List 
Processing. " 



AREA DATA 

Area variables are used to describe 
areas of storage that are to be reserved 
for the allocation of based variables. An 
area can be assigned or transmitted com- 
plete with its contained allocations; thus, 
a set of based allocations can be treated 
as one unit for assignment and input/output 
while each allocation retains its individu- 
al identity. 

A variable is given the AREA attribute 
either by its appearance in the OFFSET 
attribute or an IN option, or by explicit 
declaration, as in the following example: 

DECLARE AREA1 AREA (2000), 
AREA2 AREA; 

The number of bytes of storage to be 
reserved can be stated explicitly, as it 
has been for AREA1 in the example; other- 
wise a default size is assumed. For the 
I TSS/360 PL/I compiler, this default size is 
1000 bytes. 

For detailed information, see Part I, 
Section 14, "Based Storage and List 
Processing. " 
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either an array variable or a structure 
variable . 

Any type of problem data or program con- 
trol data can be collected into arrays or 
structures. 



ARRAYS 

Data elements having the same charac- 
teristics, that is, of the same data type 
and of the same precision or length, may be 
grouped together to form an array. An 
a r r a y is an n™dimensional collection of 
elements, all of which have identical 
attributes. Only the array itself is given 
a name. An individual item of an array is 
referred to by giving its relative position 
within the array. 

Consider the following two declarations: 

DECLARE LIST (8) FIXED DECIMAL (3) ; 
DECLARE TABLE (4,2) FIXED DECIMAL (3); 

In toe first example, LIST is declared to 
be a one-dimensional array of eight ele- 
ments, each of which is a fixed- point deci- 
mal item of three digits. In the second 
example, TABLE is declared to be a two- 
dimensional array, also of eight fixed- 
point decimal elements. 

The parenthesized number or numbers fol- 
lowing the array name in a DECLARE state- 
ment is the dimension attribute specifica- 
tion. It must follow the array name, with 
or without an intervening blank. It speci- 
fies the number of dimensions of the array 
and the bounds, or extent, of each dimen- 
sion. Since only one bounds specification 
appears for LIST, it is a one-dimensional 
array, Two bounds specifications, 
separated by a comma, are listed for TABLE; 
consequently, it is declared to be a two- 
dimensional array. 

Tne fao^nds of a dimension are the begin- 
ning and the end of that dimension. The 
e xtent is the number of integers between, 
and including, the lower and upper bounds. 
If only one integer appears in the bounds 
specification for a dimension, the lower 
bound is assumed to be 1 . The one dimen- 
sion of LIST has bounds of 1 and 8; its 
extent is 8. The two dimensions of TABLE 
have bounds of 1 and 4 and 1 and 2; the 
extents are 4 and 2. 

If the lower bound of a dimension is nob 
1, both the upper bound and the lower bound 
must be stated explicitly, with the two 
numbers connected with a colon. For 
example: 

DECLARE LIST__A (4:11); 
DECLARE LIST B (-4:3); 



In the first example, the bounds are 4 and 
11; in the second they are -4 and 3. Note 
that the extents are the same; in each 
case, there are 8 integers from the lower 
bound through the upper bound. It is 
important to note the difference between 
the bounds and the extent of an array. In 
the manipulation of array data (discussed 
in Part I, Section 4, "Expressions") 
involving more than one array, the bounds 
— not merely the extents -- must be. iden- 
tical. Although LIST, LIST_A, and LIST__B 
all have the same extent, the bounds are 
not identical. 

The bounds of an array determine the way 
elements of the array can be referred to. 
For example, assume that the following data 
items are assigned to the array LIST, as 
declared above: 

20 5 10 30 630 150 310 70 

The different elements would be referred 
to as follows: 



Reference 


Element 


LIST 


(1) 


20 


LIST 


(2) 


5 


LIST 


(3) 


10 


LIST 


(4) 


30 


LIST 


(5) 


630 


LIST 


(6) 


150 


LIST 


C7) 


310 


LIST 


(8) 


70 



Each of the numbers following the name 
LIST is a subscript . A parenthesized sub- 
script following an array name, with or 

without an intervening blank, specifies the 
relative position of a data item within the 
array. A subscripted name, such as LIST 
(4), refers to a single element and is an 
element variable. The entire array can be 
referred to by the unsubscripted name of 
the array, for example, LIST. In this 
case, LIST is an array variable. Note the 
difference between a subscript and the 
dimension attribute specification. The 
latter, which appears in a declaration, 
specifies the dimensionality and the number 
of elements in an array* Subscripts are 
used in other references to identify spe- 
cific elements within the array. 

The same data assigned to LIST_A and 

IIST_B, as declared above, would be 
referred to as follows: 



Reference 


Element 


Reference 


LIST A 


(4) 


20 


LIST B 


(-4) 


LIST A 


(5) 


5 


LIST B 


(-3) 


LIST A 


(6) 


10 


LIST B 


(-2) 


LIST A 


(7) 


30 


LIST B 


(-1) 


LIST A 


(8) 


630 


LIST B 


CO) 


LIST A 


(9) 


150 


LIST B 


(1) 


LIST A 


(10) 


310 


LIST B 


(2) 


LIST A 


(11) 


70 


LIST B 


(3) 
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Assume that the same data were assigned 
to TABLE, which is declared as a two- 
dimensional array. TABLE can te illus- 
trated as a matrix of four rows and two 
columns, as follows: 



TABLE (m f n) 


(m,l) 


(m,2> 


(l,n) 


20 


5 


(2, n) 


10 


30 


(3,n) 


630 


150 


(4,n) 


310 


70 



An element of TABLE is referred to by a 
subscripted name with two parenthesized 
subscripts, separated by a comma. For 
example, TABLE (2,1) would specify the 
first item in the second row, in this case, 
the data item 10 . 
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Arrays are not limited to two dimen- 
sions. The PL/I compiler allows as many as 
32 dimensions to be declared for an array. 
In a reference to an element of any array, 
a subscripted name must contain as many 
subscripts as there are dimensions in the 
array. 

Examples of arrays in this chapter have 
shown arrays of arithmetic data. Other 
data types may be collected into arrays. 
String arrays, either character or bit, are 
valid, as are arrays of statement labels. 

Expressions as Subscripts 

The subscripts of a subscripted name 
need not be constants . Any expression that 
yields a valid arithmetic value can be 
used. If the evaluation of such an expres- 
sion does not yield an integer value, the 
fractional portion is ignored. For System/ 
360 implementations, the integer value is 
converted, if necessary, to a fixed-point 
binary number of precision (15,0), since 
subscripts are maintained internally as 
binary integers. Note that, altnough the 
TSS/360 compiler maintains fixed-point 
binary variables of precision less than 16 
as half words , this does not apply to sub- 
script expressions. These, like most other 
compiler-created fixed-point binary tem- 
poraries (see Section 4, "Expressions and 
Data Conversion") are stored as fullwords, 
regardless of precision. 

Subscripts are frequently expressed as 
variables or other expressions. Thus, 



TABLE(I,J*K) could be used to refer to the 
different elements of TABLE by varying the 
values of I, J, and K. 



Cross Sections of Arrays 

Cross sections of arrays can be referred 
to by substituting an asterisk for a sub- 
script in a subscripted name. The asterisk 
then specifies that the entire extent is to 
be used. For example, TABLE (*,1) refers to 
all of the elements in the first column of 
TABLE. It specifies the cross section con- 
sisting Of TABLE(1,1), TABLE(2,1), TABLEC3, 
1), and TABLE (4,1). The subscripted name 
TABLE (2,*) refers to all of the data items 
in the second row of TABLE. TABLE (*,*) 
refers to the entire array. 

Note that a subscripted name containing 
asterisk subscripts represents, not a 
single data element, but an array with as 
many dimensions as there are asterisks. 
Consequently, such a name is not an element 
expression, but an array expression. 



STRUCTURES 

Data items that need not have identical 
characteristics, but that possess a logical 
relationship to one another, can be grouped 
into aggregates called structures. 

Like an array, the entire structure is 
given a name that can be used to refer to 
the entire collection of data. Unlike an 
array, however, each element of a structure 
also has a name. 

A structure is a hierarchical collection 
of names. At the bottom of the hierarchy 
is a collection of elements, each of which 
represents a single data item or an array. 
At the top of the hierarchy is the struc- 
ture name, which represents the entire 
collection of element variables. For 
example, the following is a collection of 
element variables that might be used to 
compute a weekly payroll: 

LAST_NAME 

FIRST__NAME 

R EG ULAR_ HOURS 

OVERTIME_HOURS 

REGULAR__RATE 

OVERTIMEJRATE 

These variables could be collected into 
a structure and given a single structure 
name, PAYROLL, which would refer to the 
entire collection. 



LAST^NAME 
FIRST NAME 



PAYROLL 
REGULAR_HOURS 
OVERTIME HOURS 



REGULAR__RATE 
OVERTIME RATE 
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Any reference to PAYROLL would be a 
reference to all of the element variables. 

For example: 

GET DATA (PAYROLL); 

This input statement could cause data to 
be assigned to each of the element 
variables of the structure PAYROLL. 

It often is convenient to subdivide the 
entire collection into smaller logical 
collections. In the above examples, LAST__- 
NAME and FIRST__NAME might make a logical 
ssibcollection, as might REGULAR__HQURS and 
OVERT IME_HOURS, as well as REGULAR_RATE and 
OVERTIME__RATE. In a structure, such subco- 
llections also are given names. 





PAYROLL 




NAME 


HOURS 


RATE 


FIRST 


REGULAR 


REGULAR 


LAST 


OVERTIME 


OVERTIME 



Note that the hierarchy of names can be 
considered to have different levels. At 
the first level is the structure name 
(called a major structure name); at a deep- 
er level are the names of substructures 
(called minor structure names) ; and at the 
deepest are the element names (called ele- 
mentary names) . An elementary name in a 
structure can represent an array, in which 
case it is not an element variable, but an 
array variable. 

The organization of a structure is spec- 
iried in a DECLARE statement through the 
use of level numbers. A major structure 
name must be declared with the level number 
1. Minor structures and elementary names 
must be declared with level numbers arith- 
metically greater than 1; they must be 
decimal integer constants. A blank must 
separate the level number and its asso- 
ciated name. The maximum declared level 
number permitted in a structure is 255. 
The maximum true level number permitted in 
a structure is 63. 

For example, the items of a weekly 
payroll could be declared as follows: 



DECLARE 1 



PAYROLL, 

2 NAME, 
3 LAST, 
3 FIRST, 

2 HOURS, 

3 REGULAR, 
3 OVERTIME, 

2 RATE, 

3 REGULAR, 
3 OVERTIME; 



Note : In an actual declaration of the 
structure PAYROLL, attributes woui d be 
specified for each of the elementary names. 
The pattern of indention in this example is 



used only for readability. The statement 
could be written in a continuous string as 
CECLARE 1 PAYROLL, 2 NAME, 3 LAST, etc. 



PAYROIL is declared as a major structure 
containing the minor structures NAME, 
HOURS, and RATE. Each minor structure con- 
tains two elementary names. A user can 
refer to the entire structure by the name 
PAYROLL, or he can refer to portions of the 
structure by referring to the minor struc- 
ture names. He can refer to an element by 
referring to an elementary name. 

Note that in the declaration, each level 
number precedes its associated name and is 
separated from the name by a blank. The 
numbers chosen for successively deeper 
levels need not be the immediately succeed- 
ing integers. They are used merely to spe- 
cify the relative level of a name. A minor 
structure at level n contains all the names 
with level numbers greater than n that lie 
between that minor structure name and the 
next name with a level number less than cr 
equal to n. PAYROLL might have been 
declared as follows: 

CECLARE 1 PAYROLL, 
*4 NAME, 

5 LAST, 

5 FIRST, 
2 HOURS, 

6 REGULAR, 
5 OVERTIME, 

2 RATE, 

3 REGULAR, 
3 OVERTIME; 

This declaration would result in exactly 
the same structuring as the previous 

declaration. 

The description of a major structure 
name is terminated by the declaration of 
another item with a level number 1, by the 
declaration of another item with no level 
number, or by a semicolon terminating the 
CECLARE statement. 

Level numbers an- specified with struc- 
ture names only in DECLARE statements. In 
references to the structure or its ele- 
ments, no level numbers are used. 



Qualified Names 

A minor structure or a structure element 
can be referred to by the minor structure 
name or the elementary name alone if there 
is no ambiguity. Note, however, that each 
of the names REGULAR and OVERTIME appears 
twice in the structure declaration for 
PAYROLL. A reference to either name would 
be ambiguous without some qualif xcaticn to 
irake the name unique. 
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PL/I allows the use of qualified names 
to avoid this ambiguity. A qualified name 
is an elementary name or a miner structure 
name that is made unique by qualifying it 
with one or more names at a higher level. 
In the PAYROLL example, REGULAR and OVER- 
TIME could be made unique through use of 
the qualified names HOURS .REGULAR, HOURS. 
OVERTIME, RATE. REGULAR, and RATE. OVERTIME . 

The different names of a qualified name 
are connected by periods. Blanks may or 
may not appear surrounding the period. 
Qualification is in the order of levels; 
that is, the name at the highest level must 
appear first, with the name at the deepest 
level appearing last. 

Any of the names in a structure, except 
the major structure name itself, need not 
be unique within the procedure in which it 
is declared. For example, the qualified 
name PAYROLL. HOURS. REGULAR might be 
required to make the reference unique 
(another structure, say WORK, might also 
have the name REGULAR in a minor structure 
HOURS; it could be made unique with the 
name WORK. HOURS. REGU LAR ) . All of the qual- 
ifying names need not be used, although 
they may be, if desired. Qualification 
need go only so far as necessary to make 
the name unique. Intermediate qualifying 
names can be omitted. The name PAYROLL. 
LAST is a valid reference to the name 
PAYROLL. NAME. LAST. 



ARRAYS OF STRUCTURES 

A structure name, either major or minor, 
can be given a dimension attribute in a 
DECLARE statement to declare an array of 
structures. An array of structures is an 
array whose elements are structures having 
identical names, levels, and elements. For 
example, if a structure, WEATHER, were used 
to process meteorological information for 
each month of a year, it might be declared 
as follows: 



TEMPERATURE.HIGHC3) , which would refer 
to the high temperature in March, is a sub- 
scripted qualified name . 

The need for subscripted qualified names 
becomes more apparent when an array of 
structures contains minor structures that 

are arrays. For example, consider the fol- 
lowing array of structures: 

DECLARE 1 A (6,6) , 
2 B ( 5) , 
3 C, 

3 D, 
2 E; 

Both A and B are arrays of structures. To 
identify a data item, it may be necessary 
to use as many as three names and three 
subscripts. For example, A(l, 1) .B( 2) .C 
identifies a particular C that is an ele- 
ment of B in a structure in A. 

So long as the order of subscripts 
remains unchanged, subscripts in such 
references may be moved to the right or 
left and attached to names at a lower cr 
higher level. For example, A.B.C(1,1,2) 
and A(1,1,2).B.C have the same meaning as 
A(l,l) .B(2) .C for the above array of struc- 
tures. Unless all of the subscripts are 
moved to the lowest or highest level, the 
qualified name is said to have interleaved 
subscripts ; thus, A.B(1,1,2).C has inter- 
leaved subscripts. 

An array declared within an array of 
structures inherits dimensions declared in 
the containing structure. For example, in 
the above declaration for the array of 
structures A, the array B is a three- 
dimensional structure, because it inherits 
the two dimensions declared for A. If B is 
unique and requires no qualification, any 
reference to a particular B would require 
three subscripts, two to identify the spe- 
cific A and one to identify the specific B 
within that A. 



DECLARE 1 WEATHER(12), 

2 TEMPERATURE, 

3 HIGH DECIMAL FIXED (*4,1), 
3 LOW DECIMAL FIXED(3,1>, 

2 WIND__VELOCITY, 

3 HIGH DECIMAL FIXED(3), 
3 LOW DECIMAL FIXEDC2), 

2 PRECIPITATION, 

3 TOTAL DECIMAL FIXED (3,1), 
3 AVERAGE DECIMAL FIXEDC 3, 1) ; 

Thus, a user could refer to the weither 
data for the month of July by specifying 
WEATHER (7). Portions of the July veather 
could be referred to by TEMPERATURE (7) , 
WIND_VELOCITY(7) , and PRECIPIT TION (7) , but 
TOTALC7) would refer to the total precipi- 
tation during the month of July. 



OTHER ATTRIBUTES 

Keyword attributes for data variables 
such as BINARY and DECIMAL are discussed 
briefly in the preceding sections of this 
chapter. Other attributes that are not 
peculiar to one data type may also be ap- 
plicable. A complete discussion of these 
attributes is contained in Part II, Section 
9, "Attributes." Some that are especially 
applicable to a discussion of data type and 
data organization are DEFINED, LIKE, 
ALIGNED, UNALIGNED, and INITIAL. 

The DEFINED Attribute 

The DEFINED attribute specifies that the 
named data element, structure, or array is 
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to occupy the same storage area as that 
assigned to other data. For example, 

DECLARE LIST (100,100), 

LIST_ITEM (100,100) DEFINED LIST; 

LIST is a 100 by 100 two-dimensional array. 
LIST__ITEM is an identical array defined on 
LIST. A reference to an element in LIST__I- 
TEN is the same as a reference to the 
corresponding element in LIST. 

The DEFINED attribute, along with the 
POSITION attribute, can be used to subdi- 
vide or overlay a data item. For example: 

DECLARE LIST CHARACTER (50) , 

LISTA CHARACTER! 10) DEFINED LIST, 

LISTB CHARACTER (10) DEFINED LIST 

POSITION(ll), 

LISTC CHARACTER (30) DEFINED LIST 

POSITION (21) ; 

LISTA refers to the first ten characters of 
LIST. LISTB refers to the second ten 
characters of LIST. LISTC refers to the 
last thirty characters of LIST. 



The DEFINED attribute 
to specify parts of an a 
iSUB variables, in order 
new array. The iSUB var 
variables where i can be 
decimal integer constant 
(where n represents the 
sions for the defined it 
the dummy variable (iSUB 
lower bound to the upper 
dimension specified by n 



may also be used 
rray through use of 

to constitute a 
iables are dummy 

specified as any 

from 1 through n 
number of dimen- 
em) . The value of 
) ranges from the 

bound of the 
For example: 



DECLARE A (20, 20) , 

B(10) DEFINED A (2*1SUB ,2*1SUB) ? 

B is a subset of A consisting of every even 
element in the diagonal of the array, A. 
In other words, B(l) corresponds to A(2,2) f 
E(2) corresponds to A(U,4). 



This declaration for COST_OF_LIVING is the 

same as if it had been declared: 

DECLARE 1 COST_OF_ LIVING, 

2 RENT, 
2 FOOD, 

3 MEAT, 

3 EGGS, 

3 BUTTER, 
2 TRANSPORTATION, 

3 WORK, 

3 OTHER, 
2 ENTERTAINMENT; 

Note : The LIKE attribute copies structur- 
ing, names, and attributes of the structure 
below the level of the specified name only. 
No dimensionality of the specified name is 
copied. For example, if BUDGET were 
declared as 1 BUDGET (12), the declaration 
of COST_OF_LIVING LIKE BUDGET would not 
give the dimension attribute to COST_OF__- 
LIVING. To achieve dimensionality of 
COST-OF-LIVING, the declaration would have 
to be DECLARE 1 COST_OF_IIVING (12) LIKE 
BUDGET. 

A minor structure name can be declared 
LIKE a major structure or LIKE another 
rrinor structure. A major structure name 
can be declared LIKE a minor structure or 
LIKE another major structure. 

The ALIGNED and UNALIGNED Attributes 

The ALIGNED and UNALIGNED attributes are 
used to specify the positioning in storage 
of data elements, to influence speed of 
access or storage economy respectively. 

Note: Use of the UNALIGNED attribute 
allows data interchange with FORTRAN files. 

ALIGNED In System/360 implementations 
specifies that the data element is to be 
aligned on the storage boundary correspond- 
ing to. its data type requirement. 



The LIKE Attribute 

The LIKE attribute is used to indicate 
that the name being declared is to be given 
the same structuring as the major structure 
or minor structure name following the 
attribute LIKE. For example: 

DECLARE 1 BUDGET, 
2 RENT, 
2 FOOD, 

3 MEAT, 

3 EGGS, 

3 BUTTER, 
2 TRANSPORTATION, 

3 WORK, 

3 OTHER, 
2 ENTERTAINMENT, 
1 COST_OF_LIVING LIKE BUDGET; 



UNALIGNED in Syst 
specifies that each 
stored contiguously 
preceding it: a cha 
to be mapped on the 
bit-string item is t 
tit, and a fullword 
to be mapped on the 



em/360 implementations 
data element is to be 
with the data element 
racter-string item is 
next byte boundary, a 
o be mapped on the next 
and doubleword item is 
next byte boundary. 



Defaults are applied at element level. 
The default for bit-string data, character- 
string data, and numeric character data is 
UNALIGNED,- for all other types of data, the 
default is ALIGNED. 

ALIGNED or UNALIGNED can be specified 
for element, array, or structure variables. 
The application of either attribute to a 
structure is equivalent to applying the 
attribute to all contained elements that 
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are not explicitly declared ALIGNED or 
UNALIGNED. 

The following example illustrates the 
effect of ALIGNED and UNALIGNED declara- 
tions for a structure and its elements: 



UNALIGNED BY 
DEFAULT */ 

ALIGNED EXPLICITLY */ 
ALIGNED FRON A */ 
UNALIGNED 
EXPLICITLY */ 
UNALIGNED FROM C */ 
ALIGNED EXPLICITLY */ 
UNALIGNED FROM C */ 
ALIGNED FROM A */ 
2 H; /* ALIGNED BY DEFAULT */ 

Although UNALIGNED causes economic use 
of data storage, for System/360 implementa- 
tions it will increase the amount of code 
generated to access data items that are not 
aligned on the required byte boundaries. 

The INITIAL Attribute 



DECLARE 1 STRUCTURE, 
2 X BITC2), /* 


2 A 
3 
3 


ALIGNED, /* 
B, /* 
C UNALIGNED, /* 


3 


4 D, /* 
4 E ALIGNED, /* 
4 F, /* 
G, /* 



The compiler does not allow the INITIAL 
attribute to be specified for based 

variables . 



The INITIAL attribute cannot be given 
for entry names, file names, DEFINED data, 
entire structures, parameters, task data, 
cr event data. 



Note : The CALL option cannot be used with 
the INITIAL attribute for static data. 

The INITIAL attribute cannot be used 
without the CALL option for pointer, off- 
set, or area data. An area variable is 
automatically initialized with the value of 
the EMPTY built-in function, on allocation, 
after which any specified INITIAL CALL is 
applied. 

The INITIAL attribute can be specified 
for arrays, as well as for element 
variables. In a structure declaration, 
only elementary names can be given the INI- 
TIAL attribute. 



The INITIAL attribute specifies an ini- 
tial value to be assigned to a variable at 
the time storage is allocated for it. For 
example: 

DECLARE NAME CHARACTER( 10 ) INITIAL 
( 'JOHN DOE') ; 

DECLARE PI FIXED DECIMAL (5,4) INITIAL 
(3.1416) ; 

DECLARE TABLE (100,100) INITIAL CALL 
SU BR (ALPHA) ; 



When storage is allocated 
character string "JOHN DOE* ( 
characters) will be assigned 
PI is allocated, it will be i 
the value 3.1416. Either val 
retained throughout the progr 
be changed during execution, 
example illustrates the CALL 
indicates that the procedure 
invoked to perform the initia 



for NAME, the 
padded to 10 
to it. When 
nitialized to 
ue may be 
am, or it may 

The third 
option. It 
SUBR is to be 
lization . 



For a variable that is allocated when 
the program is loaded, that is, a static 
variable, which remains in allocation 
throughout execution of the program, any 
value specified in an INITIAL attribute is 
assigned only once. Fcr automatic 
variables, which are allocated at *ach 
activation of the declaring block, any 
specified initialization is assigned with 
each allocation. For controlled variables, 
which are allocated at the execution of 
ALLOCATE statements, any spec! -.led initial- 
ization is assigned with each* allocation. 
Note, however, that this initialization can 
be overridden in the ALLOCATE statement. 



An array or an array of structures can 
be partly initialized or fully initialized. 
For example: 

DECLARE A(15) CHARACTERC 13) INITIAL 

(•JOHN DOE', 'RICHARD ROW', 
•MARY SMITH 1 ), 
B (10,10) DECIMAL FIXED (5) 

INITIAL ( (25)0, (25)1, (50)0), 
1 C(8), 

2 D INITIAL (0) , 
2 E INITIAL! (8)0); 



In this example 
ments of A are 
array is uninit 
fully initializ 
ments initializ 
and the last 50 
numbers (25, 25 
tors , that spec 
to be initializ 
where the dimen 
by D f only the 
initialized; wh 
been inherited 
are initialized 



, only the first three ele- 
initialized; the rest of the 
ialized. The array B is 
ed, with the first 25 ele- 
ed to 0, the next 25 to 1, 
to 0. The parenthesized 
and 50) are iteration f ac- 
ify the number of elements 
ed. In the structure C, 
sion (8) has been inherited 
first element of D is 
ere the dimension (8) has 
by E, all the elements of E 



When an array of structures is declared 
with the LIKE attribute to obtain the same 
structuring as a structure whose elements 
have been initialized, it should be noted 
that only the first structure in this array 
cf structures will be initialized. For 
example: 

DECLARE 1 G, 

2 H INITIAL(O), 
2 I INITIAL (0) , 
1 J(8) LIKE G; 
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In this example, only J(1).H and J(1).I are 
initialized in the array of structures. 

For STATIC arrays, iteration factors 
must be decimal integer constants; for 
arrays of other storage classes, iteration 
factors may be constants, variables, or 
expressions. 

The iteration factor should not be con- 
fused with the string repetition factor 
discussed earlier in this chapter. Consid- 
er the following example: 

DECLARE TABLE (50) CHARACTER (10) 
INITIAL ((10) 'A' , (25) (10) 9 B* , 
(24) (D'C 1 ); 



merit of TABLE is to be initialized with a 
string consisting of 10 A's, each of the 
next 25 elements is to be initialized with 
a string consisting of 10 B's, and each of 
the last 24 elements is to be initialized 
with the single character C. In the INI- 
TIAL attribute specification for a string 
array, a single parenthesized factor pre- 
ceding a string constant is assumed to be c 
string repetition factor (as in (10) 'A'). 
If more than one appears, the first is 
assumed to be an iteration factor, and the 
second a string repetition factor. For 
this reason (as in (24) (D'C), a string 
repetition factor of 1 must be inserted if 
a single string constant is to be used to 
initialize more than one element. 



This INITIAL attribute specification con- 
tains both iteration factors and repetition 
factors. It specifies that the first ele- 



The CALL option can be used to initial- 
ize arrays, except for arrays of static 
storage class. 
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SECTION 4: EXPRESSIONS AND DATA CONVERSION 



An expression is a representation of a 
value. A single constant or a variable is 
an expression. Combinations of constants 
and/or variables, along with operators and/ 
or parentheses, are expressions. An ex- 
pression that contains operators is an 
operational expression . The constants and 
variables of an operational expression are 
called operands . 

Examples of expressions are: 

27 

LOSS 
A+B 
(SQTY-QTY)*SPRICE 

Any expression can be classified as an 
element expression (also called a scalar 
expression), an array expression , or a 
structure expression . An element expres- 
sion is one that represents an element 
value. An array expression is one that 
represents an array value. A structure ex- 
pression is one that represents a structure 
value. 



I For the TSS/360 Pl/I 
variables and structure 
appear in the same expre 
variables and constants, 
appear in either array e 
structure expressions, 
within a structure or a 
that specifies a single 
is an element expression 



compiler, array 
variables cannot 
ssion. Element 

however, can 
xpressions or 
An elementary name 
subscripted name 
element of an array 



Note : If an elementary name of a structure 
is given the dimension attribute, that ele- 
mentary name is an array variable and can 
appear only in array expressions. 

In the examples that follow, assume that 
the variables have attributes declared as 
follows : 

DECLARE A (10, 10) BINARY FIXED (31), 
B(10,10) BINARY FIXED (31), 
1 RATE, 2 PRIMARY DECIMAL FIXED (4,2), 

2 SECONDARY DECIMAL FIXED (4,2), 
1 COST, 2 PRIMARY DECIMAL FIXED (4,2), 

2 SECONDARY DECIMAL FIXED (4,2), 
C BINARY FIXED (15) , 
D BINARY FIXED (15); 

Examples of element expressions are: 
C * D 

A(3,2) + B(4,8) 
RATE. PRIMARY - COST. PRIMARY 
A(4,4) * C 
RATE. SECONDARY / 4 
A (4, 6) * COST. SECONDARY 



All of these expressions are element ex- 
pressions because each operand is an ele- 
ment variable or constant (even though some 
may be elements of arrays or elementary 
names of structures) ; hence, each expres- 
sion represents an element value. 

Examples of array expressions are: 

A+B 

A * C - D 

B / 10B 

All of these expressions are array expres- 
sions because at least one operand of each 
is an array variable; hence, each expres- 
sion represents an array value. Note that 
the third example contains the binary 
fixed- point constant 10B. 

Examples of structure expressions are: 

RATE * COST 
RATE / 2 

Both of these expressions are structure ex- 
pressions because at least one operand of 
each is a structure variable; hence, each 
expression represents a structure value. 



USE OF EXPRESSIONS 

Expressions that are single constants or 
single variables may appear freely through- 
out a program. However, the syntax of many 
PL/I statements allows the appearance of 
operational expressions, so long as evalua- 
tion of the expression yields a valid 
value. 

In syntactic descriptions used in this 
publication, the unqualified term "expres- 
sion" refers to an element expression, an 
array expression, or a structure expres- 
sion. For cases in which the kind of ex- 
pression is restricted, the type of re- 
striction is noted; for example, the term 
" element-expression" in a syntactic 
description indicates that neither an array 
expression nor a structure expression is 
valid. 

Note: Although operational expressions can 
appear in a number of different PL/I state- 
ments, their roost common occurrences are in 
assignment statements of the form: 

A = B + C; 

The assignment statement has no PL/I key- 
word. The assignment symbol (=) indicates 



Section 4: Expressions and Data Conversion 29 



that the value of the expression on the 
right CB + C) is to be assigned to the 
variable on the left (A) . For purposes of 
illustration in this chapter, some examples 
of expressions are shown in assignment 
statements . 



DATA CONVERSION IN OPERATIONAL EXPRESSIONS 

An operational expression consists of 
one or more single operations. A single 
operation is either a prefix operation Can 
operator preceding a single operand) or an 
infix operation (an operator between two 
operands) . The two operands of any infix 
operation, when the operation is performed, 
usually must be of the same data type, as 
specified by the attributes of a variable 
or the notation used in writing a constant. 

Tne operands of an operation in a PL/I 
expression are automatically converted, if 
necessary , to a common representation 
before the operation is performed. General 
xules for conversion of different data 
types are discussed in the following para- 
graphs and in a later section of this 
chapter, ''Concepts of Data Conversion. " 
Detailed rules for specific cases, includ- 
ing rules for computing the precision or 
length of a converted item, can be found in 
Part II, Section 6, "Problem Data 
Conversion. " 

Data conversion is mainly confined to 
problem data. The only conversion possible 
with program control data is conversion 
between offset and pointer types. 



PROBLEM DATA CONVERSION 

Data conversion can be applied to all 
types of problem data, as listed below. 

Bit-string to Character-String 

The bit 1 becomes the character 1; the 
bit becomes the character 0. 

Character-String to Bit-string 

The character string should contain the 
characters 1 and only, in which case the 
character 1 becomes the bit 1, and the 
character becomes the bit 0. The CONVER- 
SION condition is raised by an attempt to 
convert any character other than 1 or to 
a bit. 

Character- String to Arithmetic 

The character string must be in the form 
of a signed or unsigned arithmetic constant 
(or an expression representation of a COM- 
PLEX data item) . The constant may be sur- 
rounded by blanks, but blanks must not be 



imbedded in a number. Any character other 
than those allowed in arithmetic data will 
raise the CONVERSION condition if conver- 
sion is attempted. 

Note; In the conversion, for an infix 
operation, of a character string that 
represents a fixed-point constant -- either 
decimal or binary — any fractional portion 
will be lost if it is converted to fixed- 
| point. For the TSS/360 PL/I compiler, 
integer digits will be truncated if the 
character string contains more than 5 
decimal integer digits or 15 binary digits. 
If the conversion is to floating-point, it 
will retain its fractional value. Rules 
for the precision of such conversion are 
listed in Part II, Section 6, "Problem Data 
Conversion. " 



Arithmetic to Character-String 

The value of an internal coded arithme- 
tic operand is converted to its character 
representation. The converted field is a 
character string in the form of a valid 
arithmetic constant. The length of the 
character string is dependent upon the pre- 
cision of the arithmetic data item. 



Bit-string to Arithmetic 

A bit string is interpreted as an 
unsigned binary integer and is converted to 
fixed-point binary of positive value. The 
base and scale are further converted, if 
necessary. 

Arithmetic to Bit-string 

The absolute value is converted, if 
necessary, to a real fixed-point binary 
integer. Ignoring the plus sign, the 
integer is then interpreted as a bit 
string. The length of the bit string is 
dependent upon the precision pf the origi- 
nal unconverted arithmetic data iteir. 

Arithmetic Mode Conversion 

If a complex data item is converted to a 
real data item, the result is the real part 
cf the complex item. 

A real data item is converted to a com- 
plex data item by adding an imaginary part 
cf zero. 

Arithmetic Base and Scale Conversion 

The precision of the result of an arith- 
metic base or scale conversion is dependent 
upon the precision of the original arithme- 
tic data item. The rules are listed in 
Part II, Section 6, "Problem Data 
Conversion. " 
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LOCATOR DATA CONVERSION 

Only offset to pointer conversion occurs 
as a result of an operational expression 
(locator variables are restricted to = and 
T = comparison operations), but either of 
the following types of conversion can 
result from assignment. (See also Part I f 
Section 14, "Based Storage and List 
Processing.") 

Offset to Pointer 

An offset value is converted to pointer 
by combining the offset value with the 
pointer value relating to the start of the 
area named in the OFFSET attribute. 

Pointer to Offset 

A pointer value is converted to offset 
by effectively deducting the pointer value 
for the start of the area from the pointer 
value to be converted. This conversion is 
limited to pointer values that relate to 
addresses within the area named in the OFF- 
SET attribute. 



CONVERSION BY ASSIGNMENT 

In addition to conversion performed as 
the result of an operation in the evalua- 
tion of an expression, conversion will also 
occur when a data item -- or the result of 
an expression evaluation — is assigned to 
a variable whose attributes differ from the 
attributes of the item assigned. The rules 
for such conversion are generally the same 
as those discussed above and in Part II, 
Section 6, "Problem Data Conversion." 



EXPRESSION OPERATIONS 

An operational expression can specify 
one or more single operations. The class 
of operation is dependent upon the class of 
operator specified for the operation. 
There are four class of operations — 
arithmetic, bit-string, comparison, and 
concatenation . 



ARITHMETIC OPERATIONS 

An arithmetic operation is one that is 
specified by combining operands with one of 
the following operators: 

+ .*/** 

The plus sign and the minus sign can appear 
either as prefix operators (associated with 
and preceding a single operand such as +A 
or -A) or as infix operators I associated 
with and between two operands, such as A+B 



or A-B) . All other arithmetic operators 
can appear only as infix operators. 

An expression of greater complexity can 
be composed of a set of such arithmetic 
operations. Note that prefix operators can 
precede and be associated with any of the 
operands of an infix operation. For 
example, in the expression A*-B, the minus 
sign preceding the variable B indicates 
that the value of A is to be multiplied by 
the negative value of B. 

More than one prefix operator can pre- 
cede and be associated with a single vari- 
able. More than one positive prefix opera- 
tor will have no cumulative effect, but two 
consecutive negative prefix operators will 
have the same effect as a single positive 
prefix operator. For example: 

-A The single minus sign has the effect 
of reversing the sign of the value 
that A represents. 

— A One minus sign reverses the sign of 
the value that A represents. The 
second minus sign again reverses the 
sign of the value, restoring it to 
the original arithmetic value repre- 
sented by A. 

A Three minus signs reverse the sign of 

the value three times, giving the 
same result as a single minus sign. 

Data Conversion in Arithmetic Operations 

The two operands of an arithmetic opera- 
tion may differ in type, base, mode, preci- 
sion, and scale. When they differ, conver- 
sion takes place according to rules listed 
below. Certain other rules — as stated 
below — may apply in cases of 
exponentiation. 

TYPE : Character-string operands, numeric 
character field operands (digits recorded 
in character form), and bit-string operands 
are converted to internal coded arithmetic 
type. The result of an arithmetic opera- 
tion is always in coded arithmetic form. 
Note that type conversion is the only con- 
version that can take place in an arithme- 
tic prefix operation. 

BASE : If the bases of the two operands 
differ, the decimal operand is converted to 
binary. 

MODE : If the modes of the two operands 
differ, the real operand is converted to 
complex mode (by acquiring an imaginary 
part of zero with the same base, scale, and 
precision as the real part). The exception 
to this rule is in the case of exponentia- 
tion when the second operand (the exponent 
of the operation) is fixed- point real with 
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a scale factor of zero, 
conversion is necessary. 



In such a case, no 



PRECISION: 



If only precisions differ, no 



type conversion is necessary. 

SCALE: If the scales of the two operands 
differ, the fixed-point operand is con- 
verted to floating-point scale. The excep- 
tion to this rule is in the case of 
exponentiation when the first operand is of 
floating-point scale and the second operand 
(the exponent of the operation) is fixed- 
point with a scale factor of zero, that is, 
a fixed-point integer constant or a vari- 
able that has been declared with precision 
Cp f O). In such a case, no conversion is 
necessary, but the result will be 
f loa t i ng - poi nt . 

If both operands of an exponentiation 
operation are fixed-point* conversions may 

occur, as follows: 

1. Both operands are converted to 
floating-point if the exponent has a 

precision other than (p,0). 

2. The first operand is converted to, 
floating-point unless the exponent is 

an unsigned fixed-point integer 
constant . 

3. The first operand is converted to 
floating-point if precisions indicate 
that the result of the fixed-point 
exponentiation would exceed the maxi- 
mum number of digits allowed for the 
implementation (for System/360, 15 
decimal digits or 31 binary digits) . 
Further details and examples of con- 
version in exponentiation are included 
in the section "Concepts of Data Con- 
version" in this chapter. 

Results of Arithmetic Operations 

The "result" of an arithmetic operation, 
as used in the following text, may refer to 
an intermediate result if the operation is 
only one of several operations specified in 
a single operational expression. Any 
result may require further conversion if it 
is an intermediate result that is used as 
an operand of a subsequent operation or if 
it is assigned to a variable. 

After required conversions have taken 
place, the arithmetic operation is per- 
formed- If maximum precision is exceeded 
and truncation is necessary, the truncation 
is performed on low-order fractional 
digits, regardless of base or scale of the 
operands. In some cases involving fixed- 
point data, however, high-order digits may 
sometimes be lost when scale facte :s are 
such that point alignment does not allow 
for the declared number of integer digits. 



The base, scale, mode, and precision of 
the result depend upon the operands and the 
operator involved. 

For prefix operations, the result has 
the same base, scale, mode, and precision 
as the converted operand. Note that the 
result of -A, where A is a string, is an 
arithmetic result, since A must first be 
converted to coded arithmetic form before 
the operation can be performed. 

For infix operations, the result depends 
upon the scale of the operands in the fol- 
lowing ways : 



FLOATING-POINT ; If the converted operands 
of an infix operation are of floating-point 
scale, the result is of floating-point 
scale, and the base and mode of the result 
are the common base and mode of the 
operands. The precision of the result is 
the greater of the precisions of the two 
operands . 

FIXED- POINT : If the converted operands of 
an infix operation are of fixed-point 
scale, the result is of fixed-point scale, 
and the base and mode of the result are the 
common base and mode of the operands. The 
precision of a fixed-point result depends 
upon operands, according to the rules 
listed below. 

In the formulas for computing precision, 
the symbols used are as follows; 

p represents the total number of 
digits of the result 

q represents the scale factor of 
the result 

p ± represents the total number of 
digits of the first operand 

qjL represents the scale factor of 
the first operand 

p 2 represents the total number of 
digits of the second operand 

q 2 represents the scale factor of 
the second operand 

ADDITION AND SUBTRACTION : The total number 
of digits in the result is equal to 1 plus 
the number of integer digits of the operand 
having the greater number of integer digits 
plus the number of fractional digits of the 
cperand having the greater number of frac- 
tional digits. The total number of posi- 
tions cannot exceed the maximum number of 
digits allowed (15 decimal digits, 31 
binary digits). The scale factor of the 
result is equal to the larger scale factor 
cf the two operands. 
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Formulas : 

p = 1 + maximum (pi-q^^ Pa~qa) 
♦ maximum (q A , q a ) 

q = maximum (q ± , q 2 ) 

Example: 

12354.2385 + 222.11111 
A B CD 

The total number of digits in the result 
would be equal to 1 plus the number of 
digits in A plus the number of digits in D. 
The scale factor of the result would be 
equal to the number of digits in D. Preci- 
sion of the result would be (11 , 5). 



The total number of digits in the quotient 
would be 15 (the maximum number allowed) . 
The scale factor would be 15 minus the sum 
cf 3 (A, the number of integer digits in 
the dividend) and zero (D, the number of 
fractional digits in the divisor). Preci- 
sion of the quotient would be (15,12). 

Note that any change in the nuirber of 
integer digits in the dividend or any 
change in the number of fractional digits 
in the divisor will change the precision of 
the quotient, even if all additional digits 
are zeros . 

Examples; 

00432.432 / 2 
432.432 / 2.0000 



MULTIPLICATION : The tot a 
in the result is equal to 
number of digits in opera 
number of digits in opera 
number of digits cannot e 
number of digits allowed 
tation (15 decimal, 31 bi 
factor of the result is t 
scale factors of the two 

Formulas: 

P = Pi + Pa + 1 

q = q± ♦ qa 



1 number of digits 

one plus the 
nd one plus the 
nd two. The total 
xceed the maximum 
for the impleroen- 
nary) . The scale 
he sum of the 
operands. 



Example: 



345.432 * 
A B 



22.45 
C D 



The total number of digits in the result 
would be equal to 1 plus the sum of the 
number of digits in A, B, C, and D. The 
scale factor of the result would be the sum 
of the number of digits in B and D. Preci- 
sion of the result would be (11,5). 

DIVISION : The total number of digits in 
the quotient is equal to the maximum 
allowed by the implementation (15 decimal, 
31 binary). The scale factor of the quo- 
tient is dependent upon the number of 
integer digits of the dividend (A in the 
example below), and the number of fraction- 
al digits of the divisor (D in the example 
below) . The scale factor is equal to the 
total number of digits of the result minus 
the sum of A and D. 

Formulas: 



Precision of the quotient of the first 
example would be (15,10); scale factor is 
equal to 15- (5+0). Precision of the quo- 
tient of the second example would be 
(15,8) j scale factor is equal to 15-(3+4), 



Caution : In the use of fixed-point divi- 
sion operations, care should be taken that 
declared precision of variables and 
apparent precision of constants will not 
give a result with a scale factor that can 
force the result of subsequent operations 
to exceed the maximum number of digits 
allowed by the implementation. 



EXPONENTIATION : If the second operand (the 
exponent) is an unsigned nonzero real 
fixed-point constant of precision (p,0), 
the total number of positions in the result 
is equal to one less than the product of a 
number that is one greater than the number 
cf digits in the first operand multiplied 
by the value of the second operand (the 
exponent) . The scale factor of the result 
is equal to the product of the scale factor 
of the first operand multiplied by the 
value of the second operand (the exponent). 



Note : Some special cases of exponentiation 
are defined as follows: 

1. Real mode, x**y 

a. If 3c=0 and y>0 , the result is 0. 

b. If x=0 and y<0, the ERROR condi- 
tion is raised. 



p = 15 decimal, 31 binary 

q = 15 (or 31)-((pi-q ± ) + q a > 



Example: 



432.432 / 2 
ABC 



c. If x*0 and y=0, the result is 1. 

d. If x<0 and y is not fixed- point 
with precision (p,0) , the ERROR 
condition is raised. 

Complex mode, x**y 
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a. If x=Q and y has its real part >0 
and its imaginary part =0 # the 
result is 0. 

b. If x=0 and the real part of y<0 or 
the imaginary part of y*0, the 
ERROR condition is raised. 



(As pointed out unde 
in Arithmetic Operat 
exponent is not an u 
fixed-point integer 
the total number of 
result would exceed 
or 31 binary digits, 
is converted to floa 
and the rules for fl 
exponentiation apply 

Formulas: 



r "Data Conversion 
ions," if the 
nsigned real 
constant, or if 
digits of the 
15 decimal digits 

the first operand 
ting-point scale, 
oat ing- point 

) 



p - { Cpi+1) * Cvalue-of -exponent) ) -1 
q = q ± * (value- of- exponent) 

Example: 

32 ** 5 

The total number of digits in the 
result would be 14. This is arrived 
at by multiplying a number equal to 
one plus the number of digits in the 
first operand (1+2) by the value of 
the exponent and subtracting one. The 
scale factor of the result would be 
zero (0 * 5, scale factor of the first 
operand multiplied by the value of the 
exponent) * 



unequal length, the shorter is extended on 

the right with zeros. 

The result of a bit-string operation is 
a bit string equal in length to the length 

of the operands (the two operands, after 
conversion, always are the same length). 

If either is a varying- length bit string, 
the result is of varying length. 



Bit-string operations a 
tit-fcy-bit basis. The eff 
operation is bit reversal; 
result of -,1 is 0; the res 
The result of an "and" ope 
if both corresponding bits 
other cases, the result is 
cf an "or" operation is 1 
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ether cases , the result is 
ing table illustrates the 
tit position for each of t 
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The expression X**(-N> for N>0 is 
evaluated by taking the reciprocal of 
X**N. This may cause the OVERFLOW 
condition to occur as the intermediate 
result is computed, which corresponds 
to UNDERFLOW in the original 
expression. 



More than one bit-string operation can 
be combined in a single expression that 
yields a bit-string value. 

In the following examples, if the value 
of operand A is , 010111*B, the value of 
operand B is ■ 111111 • B, and the value of 

operand C is f 110'B, then; 



BIT-STRING OPERATIONS 

A bit-string operation is one that is 
specified by combining operands with one of 
the following operators; 

i * I 

The first operator, the "not" symbol, can 
be used as a prefix operator only. The 
second and third operators, the "and" sym- 
bol and the "or" symbol, can be used as 
infix operators only. (The operators have 
the same function as in Boolean algebra.) 

Operands of a bit-string operation are, 
if necessary, converted to bit strings 
before the operation is performed. If the 
operands of an infix operation are ot 



-s A yields f IGIGGO'B 

-i C yields 'OOl'B 

C 4 B yields i 110000 , B 

A | B yields • llllll'B 

C ( B yields s lllll fi B 

A | C-,C) yields , 011111 - B 

tU-jOICtB)) yields ■110111'B 



COMPARISON OPERATIONS 

A comparison operation is one that is 
specified by combining operands with one of 
the following operators: 



i< 



<=r = 



I s >= 



These operators specify "less than," "not 
less than," "less than or equal to, " "equal 
to," "not equal to," "greater than or equal 
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to," "greater than," 
than. " 



and "not greater 



There are three types of comparisons: 

!• Algebraic , which involves the compari- 
son of signed arithmetic values in 
internal coded arithmetic form. If 
operands differ in base, scale, preci- 
sion, or mode, they are converted 
according to the rules for arithmetic 
operations. Numeric character data is 
converted to coded arithmetic before 
comparison. 

2. Character , which involves left- to- 
right, character-by-character compari- 
sons of characters according to the 
collating sequence. 

3. Bit , which involves left-to-right, 
bit-by-bit comparison of binary 
digits. 

If the operands of a comparison are not 
immediately compatible (that is, if their 
data types are appropriate to different 
types of comparison) , the operand of the 
lower comparison type is converted to con- 
form to the comparison type of the operand 
of the higher type. The priority of com- 
parison types is (1) algebraic (highest), 
(2) character string, (3) bit string. 
Thus, for example, if a bit string were to 
be compared with a fixed decimal value, the 
bit string would be converted to arithmetic 
(i.e., fixed binary) for algebraic compari- 
son with the decimal value (which would 
also be converted to fixed binary for the 
comparison) . 

If operands of a character-string com- 
parison, after conversion, are of different 
lengths, the shorter operand is extended on 
the right with blanks. If operands of a 
bit-string comparison are of different 
lengths, the shorter is extended on the 
right with zeros. 

In the execution of PL/I programs, com- 
parisons of character data will observe the 
collating sequence resulting from the 
representations of characters in bytes of 
System/360 storage, in extended binary 
coded decimal interchange code (EBCDIC) . 

The result of a comparison operation 
always is a bit string of length one; the 
value is 'l'B if the relationship is true, 
or 'O'B if the relationship is not true. 

The most common occurrences ot compari- 
son operations are in the IF statement, of 
the following format: 

IF A = B 

THEN action-if-true 
ELSE action-if-false 



The evaluation of the expression A = B 
yields either 'l'B or 'O'B. Depending upon 
the value, either the THEN portion or the 
ELSE portion of the IF statement is 
executed. 

Comparison operations need not be 
limited to IF statements, however. The 
following assignment statement could be 
valid: 

X = A < B; 

In this example, the value 'l'B would be 
assigned to X if A is less than B; other- 
wise, the value 'O'B would be assigned. In 
the same way, the following assignment 
statement could be valid: 

X = A = B; 

The first symbol (=) is the assignment sym- 
bol; the second (=) is the comparison 
operator. If A is equal to B, the value of 
X will be 'l'B; if A is not equal to B, the 
value of X will be 'O'B. 

Only the comparison operations of 
"equal" and "not equal" are valid for com- 
parisons of complex operands, or compari- 
sons of locator operands. Comparison 
operations with program control data other 
than locator data are not allowed. 



CONCATENATION OPERATIONS 

A concatenation operation is one that is 
specified by combining operands with the 
concat enat ion symbol : 



It signifies that the operands are to be 
joined in such a way that the last charac- 
ter or bit of the operand to the left will 
immediately precede the first character or 
bit of the operand to the right, with no 
intervening bits or characters. 

The concatenation operator can cause 
conversion to string type since concatena- 
tion can be performed only upon strings, 
either character strings or bit strings. 
If both operands are character strings or 
if both operands are bit strings, no con- 
version takes place. Otherwise both 
operands are converted to character 
strings. 

The results of concatenation operations 
are as follows: 



Eit String : A bit string whose length is 
equal to the sum of the lengths of the two 
bit-string operands. 
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Character String : A character string whose 
"length is equal to the sum of the lengths 
of the two character-string operands. If 
an operand requires conversion for the con- 
catenation operation, the result is depen- 
dent upon the length of the character 
string to which the operand is converted. 

For example, if A has the attributes and 
value of the constant s 010111' B, B of the 
constant f 101 f B, C of the constant •XYfZ 1 , 

and D of the constant 'AA/BB", then 

A,'|B yields •OlOllllOl'B 

AjjA||B yields • 010111010111101 • B 

C||D yields •XY.ZAA/BB 1 

0||C yields , AA/BBXY f Z t 

E | j D yields 'lOlAA/BB 1 

Note that, in the last example, the bit 
string s 101 f B is converted to the character 
sti ing * 101' before the concatenation is 
performed. The result is a character 

string consisting of eight characters. 



Note; If either of the operands of a con- 
catenation operation has the VARYING attri- 
bute, the result will be a VARYING string. 
Whe)i VARYING strings are concatenated, the 
intermediate string created has a length 
equal to the sum of the maximum lengths. 
If the maximuiii lengths are known at compile 
time and their sum exceeds 32767 f then a 
truncated intermediate string of length 
32767 will be created and an error message 
produced. If the maximum length of either 
operand is not known at compile time and 
their sum exceeds 32767, a truncated inter- 
mediate string of length 32767 will be 
created but there will be no diagnostic 
message. 

The use of adjustable VARYING strings 
can create a similar problem. When an 
operand of the concatenate operator or the 
argument of the UNSPEC function is an 
adjustable VARYING string, the length of 
the intermediate result field is not 
tested, and execution will fail. This 
situation can also occur with SUBSTR if the 
third argument is not a constant, because 
in this case the result is an adjustable 
VARYING string. 

Similarly, when a VARYING string is 
passed as an argument to a fixed-length 
string parameter, the length of the tem- 
porary argument created is the maximum 
length. If the user wishes to pass the 
current length of the VARYING string (:n, 
for example, Y-XCA)), a possible method is: 

DCL ATEMP CHARC*) CTL; 

ALLOCATE ATEMP CHAR (LENGTH CA> ) ; 
ATEMP=A ; 
Y=X C ATEMP ); 
FREE ATEMP; 



COMBINATIONS OF OPERATIONS 

Different types of operations can be 
combined within the same operational ex- 
pression. Any combination can be used. 

For example, the expression shown in the 
following assignment statement is valid: 

RESULT =A+B<C£D; 

Each operation within the expression is 
evaluated according to the rules for that 
kind of operation, with necessary data con- 
versions taking place before the operation 
is performed. 

Assume that the variables given above 
are declared as follows: 

DECLARE RESULT BIT (3), 

A FIXED DECIMAL (1> , 
B FIXED BINARY (3) , 

C CHARACTER (2) , D BIT (4); 

• The decimal value of A would be con- 
verted to binary base. 

• The binary addition would be performed, 
adding A and B. 

• The binary result would be compared 
with the converted binary value of C. 

• The bit-string result of the comparison 
would be extended to the length of the 
bit string D, and the "and" operation 
would be performed. 

• The result of the w and w operation, a 
bit string of length 4, would be 
assigned to RESULT without conversion, 
but with truncation on the right. 

The expression in this example is 
described as being evaluated operation-by- 
operation, from left to right. Such would 
be the case for this particular expression. 
The order of evaluation, however, depends 
upon the priority of the operators appear- 
ing in the expression. 

Priority of Operators 

In the evaluation of expressions, 
priority of the operators is as follows; 

** prefix* prefix- -, (highest) 

* / I 

infix* infix- | 

I 



>= 



i> 



1 



V 
(lowest) 



If two or more operators of the highest 
priority appear in the same expression, the 
order of priority of those operators is 
from right to left; that is, the rightmost 
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exponentiation or prefix operator has the 
highest priority. Each succeeding exponen- 
tiation or prefix operator to the left has 
the next highest priority. 

For all other operators, if two or more 
operators of the same priority appear in 
the same expression, the order of priority 
of those operators is from left to right. 

Note that the order of evaluation of the 
expression in the assignment statements 



RESULT 



A + B < C S D; 



is the result of the priority of the opera- 
tors. It is as if various elements of the 
expression were enclosed in parentheses as 
follows: 



(A) + (B) 

(A + E) < (C) 

(A + B < C) S 



CD) 



The order of evaluation (and, conse- 
quently, the result) of an expression can 
be changed through the use of parentheses. 
The above expression, for example, might be 
changed as follows: 

(A + B) < (C S D) 

The order of evaluation of this expres- 
sion would yield a bit string of length 
one, the result of the comparison opera- 
tion. In such an expression, those expres- 
sions enclosed in parentheses are evaluated 
first, to be reduced to a single value, 
before they are considered in relation to 
surrounding operators. Within the lan- 
guage, however, no rules specify which of 
two parenthesized expressions, such as 
those in the above example, would be evalu- 
ated first. 

The value of A would be converted to 
fixed-point binary, and the addition would 
be performed, yielding a fixed-point binary 
result (RESULT_1). The value of C would be 
converted to a bit string (if valid for 
such conversion) and the "and" operation 
would be performed. 

At this point, the expression would have 
£een reduced to: 

RESULT_1 < RESULT_2 

RESULT_2 would be converted to binary, and 
the algebraic comparison would be per- 
formed, yielding the bit-string result of 
the entire expression. 

The priority of operators is defined 
only within operands (or sub-operands). It 
does not necessarily hold truo for an 
entire expression. Consider the following 
example: 



A + (B <C) UD || E *♦ F) 

The priority of the operators specifies, in 
this case, only that the exponentiation 
will occur before the concatenation. It 
does not specify the order of the operation 
in relation to the evaluation of the other 
operand (A + (B < C) ) . 

Any operational expression (except a 
prefix expression) must eventually be 
reduced to a single infix operation. The 
operands and operator of that operation 
determine the attributes of the result of 
the entire expression. For instance, in 
the first example of combining operations 
(which contains no parentheses), the "and" 
operator is the operator of the final infix 
operation? in this case, the result of 
evaluation of the expression is a bit 
string of length 4. In the second example 
(becuase of the use of parentheses) , the 
operator of the final infix operation is 
the comparison operator, and the evaluation 
yields a bit string of length 1. 

In general, unless parentheses are used 
within the expression, the operator cf low- 
est priority determines the operands of the 
final operation. For example: 

A + B ** 3 || C* D - E 

In this case, the concatenation operator 
indicates that the final operation will be: 

(A + B ** 3) || (C * D - E) 

The evaluation will yield a character- 
string result. 

Subexpressions can be analyzed in the 

same way. The two operands of the expres- 
sion can be defined as follows: 

A + (B ** 3) 

(C * D) - E 



ARRAY EXPRESSIONS 

An array expression is a single array 
variable or an expression that includes at 
least one array operand. Array expressions 
iray also include operators — both prefix 
and infix — element variables and 
constants. 

Evaluation of an array expression yields 
an array result. All operations performed 
on arrays are performed on an element- by- 
element basis, in row-major order. There- 
fore, all arrays referred to in an array 
expression must be of identical bounds. 

Although comparison operators are valid 
for use with array operands, an array 
operand cannot appear in the IF clause of 
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an IF statement. Only an element expres- 
sion is valid in the IF clause, since the 
IF statement tests a single true or false 
result . 

N ote : Array expressions are not always ex- 
pressions of conventional matrix algebra. 

For the TSS/3 6 Compiler the level of 
nesting in array expressions is limited by 
the following rule: 

For each level of nesting of array expres- 
sions, add 2 for the maximum number of 
dimensions in the array, add 3 for each 
subscript or argument list in the expres- 
sion or assignment, and finally, add 5. 
The total for the whole nest should not 
exceed 900. 



PREFIX OPERATORS AND ARRAYS 

The result of the operation of a prefix 
operator on an array is an array of ident- 
ical bounds, each element of which is the 
result of the operation having been per- 
formed upon each element of the original 
array. For example: 



5 3-9 
1-2 7 

6 3-4 



-5 -3 9 
-1 2 -7 

-6 -3 4 



If A is the array 



then -A is the array 



INFIX OPERATORS AND ARRAYS 

Infix operations that include an array 
variable as one operand may have an element 
or another array as the other operand. 

Arra y and Element Operations 

The result of an operation in which an 
element and an array are connected by an 
infix operator is an array with bounds 
identical to the original array, each ele- 
ment of which is the result of the opera- 
tion performed upon the corresponding ele- 
ment of the original array and the single 
element. For example: 



If A is the array 



then A*3 is the array 



5 
12 

15 
36 



10 
11 

30 
33 



8 
3 

24 
9 



The element of an array-element opera- 
tion can be an element of the same array. 
For example, the expression A*A(2,3) would 
give the same result in the case of the 
array A above, since the value of A(2,3> is 
3. 



Consider the following assignment 
statement: 



A(l,2); 



Again, using the above values for A, the 
newly assigned value of A would be: 



50 100 800 
1200 1100 300 



Note that the orig 
which is 10, is us 
only the first two 
the result of the 
A, changing the va 
cf A(l,2) is used 
tions. The first 
plied by 10, the o 
all other elements 
the new value of A 



inal value for A(l,2), 
ed in the evaluation for 

elements of A. Since 
expression is assigned to 
lue of A, the new value 
for all subsequent opera- 
two elements are multi- 
riginal value of A(l f 2); 

are multiplied by 100, 
(1,2) . 



Array and Array Operations 

If two arrays are connected by an infix 
operator, the two arrays must be of ident- 
ical bounds. The result is an array with 
bounds identical to -those of the original 
arrays; the operation is performed upon the 
corresponding elements of the two original 
arrays . 

Note that the arrays must have identical 
bounds . They must have the same number of 
dimensions, and corresponding dimensions 
must have identical lower bounds and ident- 
ical upper bounds. For example, the bounds 
of an array declared X(10,6) are not ident- 
ical to the bounds of an array declared 
y (2:11,3:8) although the extents are the 
same for corresponding dimensions, and the 
number of elements is the same. 

Examples cf array infix expressions are: 



If A is the array 



and if B is the array 



then A+B is the array 



and A*B is the array 



2 


4 


3 


6 


1 


7 


4 


8 


2 


1 


5 


7 


8 


3 


4 


6 


3 


1 


3 


9 


10 


14 


4 


11 


10 


11 


3 


2 


20 


21 


48 


3 


28 


24 


24 


2 
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A rray and Structure Operation s 

For the TSS/360 PI/I compiler, no 
reference can be made to both an array and 
a structure in the same expression or in 
the same assignment statement, 

Data Conversion in Array Expressions 

The examples in this discussion of array 
expressions have shown only single arithme- 
tic operations. The rules for combining 
operations and for data conversion of 
operands are the same as those for element 
operations . 



STRUCTURE EXPRESSIONS 

A structure expression is a single 
structure variable or an expression that 
includes at least one structure operand and 
does not contain an array operand. Element 
variables and constants can te operands of 
a structure expression. Evaluation of a 
structure expression yields a structure 
result. A structure operand can be a major 
structure name or a minor structure name. 

Although comparison operators are valid 
for use with structure operands, a struc- 
ture operand cannot appear in the IF clause 
of an IF statement. Only an element ex- 
pression is valid in the IF clause, since 
the IF statement tests a single true or 
false result. 

All operations performed on structures 
are performed on an element-by-element 
basis. Except in a BY NAME assignment 
(seebelow), all structure variables appear- 
ing in a structure expression must have 
identical structuring. 

Identical structuring means that the 
structures must have the same minor struc- 
turing and the same number of contained 
elements and arrays and that the position- 
ing of the elements and arrays within the 
structure (and within the minor structures 
if any) must be the same. Arrays in corre- 
sponding positions must have identical 
bounds. Names do not have to be the same. 
Data types of corresponding elements do not 
have to be the same, so long as valid con- 
version can be performed. 

For the TSS/360 Compiler the level of 
nesting in structure expressions is limited 
by the following rule: 

For each level of nesting of structure ex- 
pressions, add 2 for the maximum number of 
dimensions in the structure, add 2 for the 
maximum level in a structure r qpression, 
add 3 for each subscript or argument list 
in the expression or assignment, and final- 



Ily, add 15. The total for the whole nest 
should not exceed 900. 

PREFIX OPERATORS AND STRUCTURES 

The result of the operation of a prefix 
operator on a structure is a structure of 
identical structuring, each element of 
which is the result of the operation having 
been performed upon each element of the 
original structure. 

Note : Since structures may contain ele- 
ments of many different data types, a pre- 
fix operation in a structure expression 
<would be meaningless unless the operation 
can be validly performed upon every element 
represented by the structure variable, 
which is either a major structure name or a 
minor structure name. 



INFIX OPERATORS AND STRUCTURES 

Infix operations that include a struc- 
ture variable as one operand may have an 
element or another structure as the other 
operand. 

Structure operands in a structure ex- 
pression need not be major structure names. 
A minor structure name, at any level, is a 
structure variable. Thus, if M.N is a 
irinor structure in the major structure M, 
the following is a structure expression: 

M.N £ 'lOlO^ 

Structure and Element Operations 

When an operation has one structure and 
cne element operand, it is the same as a 
series of operations, one for each element 
in the structure. Each sub-operation 
involves a structure element and the single 
element . 

Consider the following structure: 



If X is an element variable, then A * 
equivalent to: 



X is 



A.C 
A.D 
A.E 
A.G 
A.H 
A.I 



X 
X 
X 
X 
X 
X 
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Structure and Structure Operations 



ONE. PARTI. RED = THREE. PARTI. RED; 



When an operation has two structure 
operands, it is the same as a series of 
element operations, one for each corre- 
sponding pair of elements. 

For example, if A is the structure shown 
in the previous example and if M is the 
following structure: 



1 M 




2 N 




3 


O 


3 


P 


3 


Q 


2 R 




3 


s 


3 


T 


3 


U 


then A | | M is 


equivalent to: 


A.C | 


M.O 


A.D 1 


M.P 


A.E | 


M.Q 


A.G | 


M.S 


A.H | 


M.T 


A.I | 


M.U 


Structure Assignment BY NAME 



One exception to the rule that operands 
of a structure expression must have the 
same structuring is the case in which the 
structure expression appears in an assign- 
ment statement with the BY NAME option. 

The BY NAME appears at the end of a 
structure assignment statement and is pre- 
ceded by a comma. Examples are shown 
below. 

Consider the following structures and 
assignment statements: 



1 ONE 



1 TWO 



1 THREE 



PARTI 

3 RED 

3 ORANGE 

PART 2 

3 YELLOW 

3 BLUE 

3 GREEN 



PARTI 
3 BLUE 
3 GREEN 
3 RED 
PART 2 
3 BROWN 
3 YELLOW 



PARTI 
3 RED 
3 BLUE 
3 BROWN 
PART2 
3 YELLOW 
3 GREEN 



ONE = TWO, BY NAME; 

ONE. PARTI = THREE. PARTI, BY NAME; 

ONE = TWO + THREE, BY NAME; 

The first assignment statement would be the 
same as the following: 

ONE. PARTI. RED = TWO. PARTI. RED; 

ONE. PART 2. YELLOW = TWO. PART 2 .YELLOW ; 

The second assignment statement would be 
the same as the following: 



The third assignment statement would be the 
same as the following; 

ONE. PARTI. RED = TWO . PARTI . RED 

+ THREE. PARTI. RED; 

ON E.PART2. YELLOW = TWO. PART2. YELLOW 

♦ THREE. PART2. YELLOW; 

The BY NAME option can appear in an 
assignment statement only. It indicates 
that assignment of elements of a structure 
is to be made only for those elements whose 
names are common to both structures. 
Except for the highest- level qualifier spe- 
cified in the assignment statement, all 
qualifying names must be identical. 

If an operational expression appears in 
an assignment statement with the BY NAME 
option, operation and assignment are per- 
formed only upon those elements whose names 
have been declared in each of the struc- 
tures. In the third assignment statement 
above, no operation is performed upon ONE. 
PART2. GREEN and THREE. PART 2 .GREEN, because 
GREEN does not appear as an elementary name 
in PART2 of TWO. 



OPERANDS OF EXPRESSIONS 

An operand of an expression can be a 
constant, an element variable, an array 
variable, or a structure variable. An 
operand can also be an expression that 
represents a value that is the result of a 
computation, as shown in the following 
assignment statement: 

A = B * SQRTCC) ; 

In this example, the expression SQRT(C) 
represents a value that is equal to the 
square root of the value of C. Such an ex- 
pression is called a function reference . 

FUNCTION REFERENCE OPERANDS 

A function reference consists of a name 
and, usually, a parenthesized list of cne 
cr more variables, constants, or other ex- 
pressions. The name is the name of a block 
of coding written to perform specific com- 
putations upon the data represented by the 
list and to substitute the computed value 
in place of the function reference. 

Assume, in the above example, that C has 
the value 16. The function reference SQRT 
(C) causes execution of the coding that 
would compute the square root of 16 and 
replace the function reference with the 
value 4. In effect, the assignment state- 
ment would become: 

A = B * 4; 
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The use of a function reference is not 
limited to operands of operational expres- 
sions. A function reference is # in itself, 
an expression and can be used wherever an 
expression is allowed. It cannot be used 
in those cases where a variable represents 
a receiving field, such as to the left of 
an assignment symbol. 

There are, however, ten built-in func- 
tions that can be used as pseudo-variables . 
A pseudo-variable is a built-in function 
name that is used in a receiving field. 
Consider the following example: 

DECLARE A CHARACTER C 10) , 
B CHARACTER (30) ; 

3UBSTR(A,6, 5) = SUBSTR ( B r 20, 5) ; 

In this assignment statement, the SUBSTR 
built-in function name is used both in a 
normal function reference and as a 
pseudo-variable. 

The SUBSTR built-in function extracts a 
substring of specified length from the 
named string. As a pseudo-variable, it 
indicates the location, within a named 
'string, that is the receiving field. 

In the above example, a substring five 
characters in length, beginning with char- 
acter 20 of the string B, is to be assigned 
to the last five characters of the string 
A. That is, the last five characters of A 
are to be replaced by characters 20 through 
2** of B. The first five characters of A 
remain unchanged, as do all of the charac- 
ters of B. 

All ten of the built-in functions that 
can be used as pseudo-variables are dis- 
cussed in Part II, Section 7, "Built-in 
Functions and Pseudo-Variables". No user- 
written function can be used as a 
pseudo- variable. 



CONCEPTS OF DATA CONVERSION 

Data conversion is the transformation of 
the representation of a value from one form 



to another. PL/I makes very few restric- 
tions upon the use of the available forirs 
of data representation or upon the mixing 

of different representations within an 

expression. 
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This section is concerned primarily with 
the concepts of conversion operations. 
Specific rules for each kind of conversion 
are listed in Part II, Section 6, "Problem 
Data Conversion." Earlier sections of this 
chapter discuss circumstances under which 
conversion can occur during evaluation of 
expressions. This section deals with the 
processes of the conversion. 

The subject of conversion can be consi- 
dered in two parts, first, determining the 
target attributes, and, second, the conver- 
sion operation with known source and target 
attributes. This section deals with deter- 
mining target attributes. Rules for con- 
version operations are given in Part II, 
Section 6, "Problem Data Conversion." 
Within each section, here and in Part II, 
arithmetic conversion and type conversion 
are considered separately. 

Tne target of a conversion is the 
receiving field to which the converted 
value is assigned. In the case of a direct 
assignment, such as A = B, in which conver- 
sion must take place, the variable to the 
left of the assignment symbol (in this 
case. A) is the target. Consider the fol- 
lowing example, however: 

DECLARE A CHARACTER (8) # 

B FIXED DECINAL(3,2), 
C FIXED BINARY (10) ; 

A = B + C; 

During the evaluation of the expression B+C 
and during the assignment of that result, 
there are four different targets, as 

follows : 

1. The compiler- created temporary to 
which the converted binary equivalent 
of B is assigned 

2. The compiler-created temporary to 
which the binary result of the addi- 
tion is assigned 
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3. The temporary to which the converted 
decimal fixed-point equivalent of the 
binary result is assigned 

i\ m A, the final destination of the 
result, to which the converted 
character- string equivalent of the 
decinal fixed-point representation of 
the value is assigned 

The attributes of the first target are 
determined frcm the attributes of the 
source (B), from the operator, and from the 
attributes of the other operand (if one 
operand of an arithmetic infix operator is 
binary, the other is converted to binary 
before evaluation). The attributes of the 
second target are determined from the 
attributes of the source (c and the con- 
verted representation of B) . The attri- 
butes of the third target are determined in 
part frorr the source (the second target) 
and in part from the attributes of the 
eventual target (A) . (The only attribute 
determined from the eventual target is 
DECIMAL, since a binary arithmetic repre- 
sentation must be converted to decimal 
representation before it can be converted 
to a character string.) The attributes* of 
the fourth target (A) are known from the 
DECLARE statement. 

When an expression is evaluated, the 
target attributes usually are partly 
derived from the source, partly from the 
operation being performed, and partly from 
the attributes of a second operand- Some 
assumptions may be made, and some implemen- 
tation restrictions (for example, maximum 
precision) and conventions exist. After an 
expression is evaluated, the result may be 
further converted. In this case, the tar- 
get attributes usually are independent of 
the source. Since the process of determin- 
ing target attributes is different for ex- 
pression operands and for the results of 
expression evaluation, the two cases are 
dealt with separately. 

A conversion always involves a source 
data item and a target data item, that is, 
the original representation of the value 
and the converted representation of the 
value. All of the attributes of both the 
source data item and the target data item 
are known, or assumed, at compile time. 
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The maximum number of temporary results 
which may exist during the evaluation of an 
expression or during an assignment state- 
ment is 200. An estimate of the number of 
temporary results which may exist during 
the evaluation of an expression can be 
obtained frorr the following; 

At each level of parentheses, count one for 
each operator which is forced to be evalua- 
ted before an inner level of parentheses. 
For each such operator, count one for each 
operand which requires conversion before 
use, count one for each nested function, 
count one for each subscripted variable 
used as a target in an assignment state- 
ment, and finally, count one for each 
pseudo-variable and each argument of a 
pseudo- variable. 

It should be realized that constants 
also have attributes? the constant 1.0 is 
different from the constants 1, 'I'fi, '1*, 
IB, or 1E0. Constants may be converted at 
compile time or at execution time, but in 
either case, the rules are the same. 



TARGET ATTRIBUTES FO R T YPE CONVERSION 

When an expression operand requires type 
conversion, some target attributes must be 
assumed or deduced from the source. Some 
of these assumptions can be made based on 
the operator, as shown in Figure 2. 



BIT TO CHARACTER AND CHARACTER TO BIT 

In the conversion of bit to character, 
and character to bit, the length of the 
target (in bits or characters) is the same 
as the length of the source (in bits or 
characters) . 



r T _„_ . .„ 

| Operator | Target Type 

t + _ „„ _„_ 

* _ * / ** | coded arithmetic 

bit string 




character string (unless 
both operands are bit 

strings) 

arithmetic, unless bcth 

operands are strings; then 
character string, unless 
both operands are bit 
strings; then tit string 



Figure 2. Target Types for Expression 
Operands 
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ARITHMETIC TO STRING 
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STRING TO ARITHMETIC 

In the conversion of fcit-string or 
character-string data to arithmetic, the 
string must consist of digits that repre- 
sent a valid arithmetic constant. The com- 
piler has no way of determining the attri- 
Dutes of the constant represented by the 
string; therefore, attributes must be 
assumed for the target. 



In the case of character 
arithmetic conversion, the a 
assumed for the target are t 
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Target Attributes for Arithmetic Expression 
Operands 

Except for exponentiation, the target 
attributes for arithmetic conversion are 
assumed as follows: 



BINARY 



FLOAT 



COMPLEX 



precision 
cf source 



unless both operands are DECIM- 
AL, in which case no base con- 
version is performed 

unless both operands are FIXED, 
in which case no scale conver- 
sion is performed 

unless both operands are REAL, 
in which case no mode conver- 
sion is performed 

unless base or scale conversion 
is performed (see Figure 3, 
"Precision for Arithmetic 
Conversion" ) 



In the case of exponentiation, the base 
and precision are determined as for other 
operations. The target scale of the first 
operand is always FLOAT unless the first 
operand source is FIXED and the second 
operand (the exponent) is an unsigned 
fixed- point integer constant with a value 
small enough that the result of the 
exponentiation will not exceed the maximum 
number of digits allowed (for System/360 
implementations, 31, if binary, or 15, if 
decimal). The target scale of the second 
operand is FLOAT unless it is an integer 
constant or a variable of precision (p,0). 
If either of the operands is COMPLEX, the 
target mode is COMPLEX for both operands 



Source Attributes 



Target Attributes 



Target Precision 



DECIMAL FIXED (p,q) 
DECIMAL FIXED (p,q) 
DECIMAL FIXED(p,q) 
DECIMAL FLOAT (p) 
BINARY FIXED (p,q) 
BINARY FIXED (p,q) 
BINARY FIXED (p,q) 
BINARY FLOAT (p) 



DECIMAL FLOAT 
BINARY FIXED 
BINARY FLOAT 
BINARY FLOAT 
BINARY FLOAT 
DECIMAL FIXED 
DECIMAL FLOAT 
DECIMAL FLOAT 



h 



l+p*3.32, q*'3.32 
p*3.32 

p*3.32 

P 

l+p/3.32, q/3.32 

p/3.3 2 
p/3.32 



H 



Note: Conversion from floating- poxnt to fixed-point scale will occur only when a target 



precision is known, as in assignment to a fixed-pcint variable. If the target 
precision is incapable of holding che floating-point value, truncation on both left 
and right will occur, and the SIZE condition will be raised (if enabled) if significant 
digits are lost. 



Figure 



Precision for Arithmetic Conversion 
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unless the second operand is a REAL integer 
constant or variable of precision (p,0). 
In either case, the target mode for the 
second operand is REAL (that is, its mode 
is not converted). 

In the examples of exponentiation shown 
below, the variables are those named in the 
following DECLARE statement: 

DECLARE A FIXED DECIMAL C 2) , 

B FIXED DECIMAL (3 f 2) , 

C FLOAT DECIMAL (4), 

D FLOAT DECIMAL (7) , 

E FIXED DECIMAL (8) , 

F FIXED DECIMALC15), 

G COMPLEX FLOAT DECIMAL(6); 

Note : If only one digit appears in the 
precision attribute specification for a 
fixed-point variable, the scale factor is, 
r.y default, zero; the precision is (p,0). 



Precisio n and Length of Expression Operand 
Target s 

The following rules apply to all calcu- 
lations of precision and length: 



Precision and length specifications 
are always integers. If any of the 
calculations given below produces a 
nonintegral value, the next largest 
integer is taken as the resulting pre- 
cision. In the case of scale factors, 
which can be negative, it is the abso- 
lute (positive) value that is used to 
take the next largest integer; the 
result, of course, will be negative if 
the source scale factor is negative. 

The following illustrates how preci- 
sion would be computed in a conversion 
from DECIMAL FIXED (13,-4) to EINARY 
FIXED: 



D ** C No conversion necessary. Both 
operands are floating-point. 

A ** 4 No conversion necessary. 

Second operand is unsigned* 
fixed- point integer constant, 
and the result will not exceed 
15 digits. 

D ** 5 No conversion necessary. First 
operand is floating-point; 
second is fixed-point with pre- 
cision ( p, 0) . 

D ** A No conversion necessary. First 
operand is floating-point; 
second is fixed-point with pre- 
cision (p, 0) . 

E ** A First operand is converted to 
floating-point because second 
operand is not unsigned fixed- 
point integer constant. Second 
operand Is not converted 
because it has precision (p,0). 

D ** B Second operand is converted to 
floating-point because it does 
not have precision (p,0). Even 
if B had an integer value with 
a fractional part of zero, it 
still would be converted, since 
its declared precision is 
(3,2) . 

G ** B First operand is complex. 

Second operand is converted to 
floating-point complex because 
its precision is not (p,0). 

Note : All of these examples would be the 
same if they had been declared binary rath- 
er than decimal, except that the maximum 
number of binary digits allowed is 31. 



1 + 13 * 3.32 = 44.16 resulting number 

of digits (p) is 
45 



2. 



■4 * 3.32 = -13.28 



resulting scale 
factor (q) is 
-14 



Thus, the resulting precision is (45,- 
14); however, due to rule 2 below, it 
becomes (31,-14). 

There is an implementation-defined 
maximum for the precision of each 
arithmetic representation. If any 
calculation yields a value greater 
than the implementation-defined liirit, 
then the implementation limit is used 
instead. In System/360 implementa- 
tions, these limits are: 



FIXED DECIMAL 

FIXED BINARY - 

FLOAT DECIMAL 

FLOAT BINARY - 



- 15 digits 
31 digits 

- 16 digits 
53 digits 



Because of the particular values for 
these implementations, these limits 
wii± usually come into effect only for 
conversions from fixed-point decimal 
to fixed-point binary. 

The scale factor for both binary and 
decimal base has the range +127 to 
-128 in System/360 implementations. 
This limit will rarely concern the 
user . 



Precision for Arith metic Conversion s 

Figure 3 gives the target precision for 
an operand if base or scale conversion 
occurs. 



44 



j Source Attributes 

j. . 

[DECIMAL FIXED (p f q) 



j Conditions 



I 



Target Length 

P*3 

p+3*k 

(where k = number of decimal 

digits to express scale 
factor) 

p + 6 

Same as source 



If p>=q>=0 

If q>p 
or 
q negative 



[DECIMAL FLOAT (p) 
[Numeric character field 

L . 

Figure 4 . Lengths of Character-String Targets 



The target precision of one? operand of 
an expression is not affected by the preci- 
sion of the other operand. This can have a 
significant effect on accuracy, particular- 
ly if one of the operands is a constant. 



Lengths of Character-String Targets 

The length of a character-string target 
is related to the precision of the decimal 
source, as shown in Figure 4. 

Note : If a binary data item is converted 
to character, it is first converted to 
decimal. The precision of this intermedi- 
ate conversion result controls the length 
of the final character-string target. 
Algorithms for computing the intermediate 
precision of a decimal item converted from 
binary are shown in Figure 3, 

For complex coded arithmetic sources, 
the target length is one greater than twice 
the length of the target for the corre- 
sponding real source. For complex numeric 
character data, the target length is twice 
the length of the real part of the source. 

Lengths of Bit-string Targets 

When converting arithmetic operands to 
bit string, the arithmetic source is con- 
verted to a positive binary integer. The 
precision of the binary integer target is 
the same as the length of the bit-string 
target as given in Figure 5. 



r . — . T 

(Source Attributes f Target Length 



h 

(DECIMAL FIXED Cp f q) 

! 

(DECIMAL FLOAT Cp) 

i 

(BINARY FIXED (p # q> 



Cp-q)*3.32 
p*3.32 

p-q 
P 



(BINARY FLOAT (p) 

i . . . x 

Figure 5. Lengths of Bit-String Targets 



Note that p-q represents the number of 
binary or decimal digits to the left of the 
point. This could be zero or negative, in 
which case no conversion is performed and, 
for the TSS/360 PL/I compiler, the final 
result is a null string. 

Conversion of the Value of an Expression 

The result of a completely evaluated ex- 
pression may require further conversion. 
The circumstances in which this can occur, 
and the target attributes for each situa- 
tion, are given in Figure 6. In addition, 
certain built-in functions cause conver- 
sion. Any subscript reference is converted 
to binary integer. 



CONVERSI ON OPERATIONS 

As in the case of determining target 
attributes, conversion operations may also 
be considered in two staqes: type conver- 
sion and arithmetic conversion. For 
example, when a character-string source is 
converted to a coded arithmetic target, the 
string is first converted to an arithmetic 
form whose attributes are determined by the 
constant expressed by the string. This 
intermediate result is then converted (if 
necessary) to the attributes of the target. 
These two stages may not be separated in an 
actual implementation, but for the purpose 
of description it is convenient to consider 
them separately. 

There are six cases of type conversion: 

Arithmetic to character-string 
Character-string to arithmetic 
Arithmetic to bit-string 
Bit-string to arithmetic 
Character-string to bit-string 
Bit-string to character-string 

For specific rules for each of the cases 
cf type conversion and for arithmetic con- 
version, see Part II, Section 6, "Problem 
Data Conversion. " 
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Figure 6. Circumstances that can Cause Conversion 



THE CONVERSION, SIZE, FIXEDOVERFLQW , AND 
OVERFLOW CONDITIONS 

When data is converted from one repre- 
sentation to another, the CONVERSION or 
SIZE conditions may be raised. The OVER- 
FLOW and FIXEDOVERFLOW conditions are 
raised only when the result of an arithme- 
tic operation exceeds the implementation- 
defined limit. When an operand is con- 
verted from one representation to another, 
if the value of the result will not fit in 
the declared precision for the new repre- 
sentation, the SIZE condition is raised. 

The SIZE condition is raised whtji signi- 
ficant digits are lost from the left-hand 



side of an arithmetic value. This can 
occur during conversion within an expres- 
sion, or upon assigning the result of an 
expression. It is not raised in conversion 
to character string or bit string even if 
the value is truncated. It is raised on 
conversion to E or F format in edit- 
directed transmission if the field width 
specified will not hold the value of the 
list item. The SIZE condition is normally 
disabled, so an interruption will occur 
only if the condition is raised within the 
scope of a SIZE prefix. 

The CONVERSION condition is raised when 
the source field contains a character that 
is invalid for the conversion being per- 
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formed. For example, CONVERS 
raised if a character string 
verted to arithmetic contains 
other than these allowed in a 
stants, or if a character str 
being converted to bit contai 
ter other than and 1. Each 
acter raises the CONVERSION c 
so a single conversion operat 
several interruptions if more 
invalid character is encounte 
VERSION condition is normally 
when the condition is raised, 
tion will occur- It can be d 
NOCONVERSION prefix, in which 
interruption will not occur w 
tion is raised. 



ION would be 
being con- 
any character 
rithmetic con- 
ing that is 
ns any charac- 
invalid char- 
ondition once, 
ion causes 

than one 
red. The CON- 
enabled, so 
an interrup- 
isabled by a 

case an 
hen the condi- 



Note that the OVERFLOW and FIXE DOVER FLOW 
conditions are raised when an implementa- 
tion maximum is exceeded, while the SIZE 
condition is raised when a declared preci- 
sio n is exceeded. For example, if the 
addition of two binary half word values 
resulted in an overflow into a sixteenth 
digit position, and the result were 
assigned to a binary halfword variable, 
SIZE would be raised (if enabled). Note 
that, in such a case, SIZE would be the 
only indication that an error had occurred, 
whereas if a similar situation arose with 
fullword binary values (i.e., an attempted 
overflow past the thirty-first digit posi- 
tion), FIXEDCVERFLOW would be raised during 
the actual computation, before the attempt. 
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SECTION 5: STATEMENT CLASSIFICATION 



This section classifies statements 
according to their functions. Statements 
in each functional class are listed, the 
purpose of each statement is described, and 

examples of their use are shown. 

A detailed description of each statement 
is not included in this section tut may be 
found in Part II, Section 10, "Statements." 



CLAS SES OF STATEMENTS 

Statements can be grouped into the fol- 
lowing six classes: 

Descriptive 

Input/Output 

Data Movement and Computational 

Program Structure 

Preprocessor 

Control 

Exception Control 

The names of the classes have been chosen 
for descriptive purposes only; they have no 
fundamental significance in the language. 
Some statements are included in more than 

one class, since they can have more than 
one function. 



DECLARE statements are always needed for 
fixed-point decimal and floating-point 
binary variables, character- and bit-string 
variables, label variables, arrays and 
structures, static, controlled, and based 
variables, offset variables, and all data 
with the PICTURE attribute. An ENTRY 
declaration must be made in a DECLARE 
statement for the name of any function that 
returns a value with attributes different 
from the default attributes that would be 
assumed for the name — FIXED BINARY (15) if 
the first letter of the name is I through 
N; otherwise, DECIMAL FLOAT! 6) . (The 
default precisions are those defined for 
System/360 implementations.) An ENTRY 
declaration also must be made if arguments 
and parameters do not match exactly, as may 
be the case when constants are passed as 
arguments . 

DECLARE statements may also be an impor- 
tant part of the documentation of a pro- 
gram; consequently, users may make liberal 
use of declarations, even when default 
attributes apply or when a contextual 
declaration is possible. Because there are 
no restrictions on the number of DECLARE 
statements, different DECLARE statements 
can be used for different groups of names. 
This can make modification easier and the 
interpretation of diagnostics clearer. 



DESCRIPTIVE STATEMENTS 



Other Descriptive Statements 



When a PL/I program is executed, it may 
manipulate many different kinds of data. 
Each data item, except a constant, is 
referred to in the program by a name. The 
PL/I language requires that the properties 
(or attributes) of data items referred to 
must be known at the time the program is 
compiled. There are a few exceptions to 
this rule; the bounds of the dimensions of 
arrays, the length of strings, and some 
file attributes may be determined during 
execution of the program. 

The DECLARE Statement 

The DECLARE statement is the principal 
means of specifying the attributes of a 
name. A name used in a program need not 
always appear in a DECLARE statement; its 
attributes often can be determined by con- 
text. If the attributes are not specific- 
ally declared and if they cannot be deter- 
mined by context, then default rules are 
applied. The combination of default rules 
and context determination can make it unne- 
cessary, in some cases, to use a DECLARE 
statement. 



The OPEN statement allows certain attri- 
butes to be specified for a file naire and 
iray, therefore, also be classified as a 
descriptive statement. The FORMAT state- 
ment may be thought of as describing the 
layout of data on an external medium, such 
as on a page or an input card. 



INPUT/OUTPUT STATEMENTS 

The principal statements of the input/ 
output class are those that actually cause 
a transfer of data between internal storage 
and an external medium. Other input/output 
statements, which affect such transfers, 
may be considered input/output control 
statements . 

In the following list, the statements 
that cause a transfer of data are grouped 
into two subclasses, RECORD I/O and STREAM 
I/O: 

RECORD I/O Transfer Statements 
READ 
WRITE 
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REWRITE 

LOCATE 

DELETE 

STREAM I/O Transfer Statements 



boundaries generally are ignored; data is 
considered to be a stream of individual 
data items, either coming from CGET) or 
going to (PUT) the external medium. 



GET 
PUT 

I/O Control Statements 

OPEN 

CLOSE 

UNLOCK 

A related statement, discussed with 
these statements, is the DISPLAY statement. 

There are two important differences 
between STREAM transmission and RECORD 
transmission. In STREAM transmission, each 
data item is treated individually, whereas 
RECORD transmission is concerned with 
collections of data items (records) as a 
whole. In STREAM transmission, each item 
may be edited and converted as it is trans- 
mitted; in RECORD transmission, the record 
on the external medium is an exact copy of 
the record as it exists in internal 
storage, with no editing or conversion 
performed. 

As a result of these differences, record 
transmission is particularly applicable for 
processing large files that are written in 
an internal representation, such as in 
binary or packed decimal. Stream transmis- 
1 sion can be used for processing typed or 
keypunched data and for producing readable 
output, where editing is required. Since 
files for which stream transmission is used 
tend to be smaller, the larger processing 
overhead can be ignored. 



The GET and PUT statements may transmit 
a list of items in one of three modes, 
data-directed, list-directed, or edit- 
directed. In data-directed transmission, 
the names of the data items, as well as 
their values, are recorded on the external 
iredium. In list-directed transmission, the 
data is recorded externally as a list of 
constants, separated by blanks or commas. 
In edit-directed transmission, the data is 
recorded externally as a string of charac- 
ters to be treated character by character 
according to a format list. 
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Note; 



The GET and PUT statements can also 



be used for internal data movement, by 
specifying a string name in the STRING 
option instead of specifying the FILE 
option. Although the facility may be used 
with READ and WRITE statements for moving 
data to and from a buffer, it is not actu- 
ally a part of the input/output operation. 
GET and PUT statements with the STRING 
option are discussed in the section "Data 
Movement and Computational Statements," in 
this section. 



RECORD I/O Transfer Statements 

The READ statement transmits records 
directly into working storage or makes 
records available for processing. The 
WRITE statement creates new records, 
transferring collections of data to the 
output device. The LOCATE statement allo- 
cates storage for a variable within an out- 
put buffer, setting a pointer to indicate 
the location in the buffer, having pre- 
viously caused any record already located 
in a buffer for this file to be written 
out. 

The REWRITE statement alters existing 
records in an UPDATE file. The DELETE 
statement removes records from an UPDATE 
file. 

STREAM I/O Transfer Statement s 

Only sequential files can be processed 
with the GET and PUT statements. Record 



Input/Output Control Statements 

The OPEN statement associates a file 
name with a data set and prepares the data 
set for processing. It may also specify 
additional attributes for the file. 

A;* OPEN statement need not always be 
written. Execution of any input or output 
transmission statement that specifies the 
name of an unopened file will result in an 
automatic opening of the file before the 
data transmission takes place. 

The OPEN statement may be used to 
declare attributes for a file; for a PRINT 
file, the length of each printed line and 
the number of lines per page can be speci- 
fied only in an OPEN statement. The OPEN 
statement can also be used to specify a 
name (in the TITLE option) other than the 
file name, as a link between the data set 
and the file. 
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The CLOSE statement dissociates a data 
set. from a file. All files are closed at 
termination of a program, so a CLOSE state- 
ment is not always required. 

The UNLOCK statement is accepted, but is 
of no significance to the TSS/360 compiler, 
since TSS/360 data management automatically 
locks records being read, if the file has 
been opened for direct access. 

T he DISPLAY Statement 

Trie DISPLAY statement is used to write 
messages on the user's terminal. It may 
also be used, with the REPLY option, to 
allow the user to communicate with the pro- 
gram by typing in a code or a message. The 
REPLY option may be used merely as a means 
of suspending program execution until the 
user acknowledges the message. 



LATA MOVEMENT AND COMPUTATIONAL STATEMENTS 

Internal data movement involves the as- 
signment of the value of an expression to a 
specified variable. The expression may be 
a constant or a variable, or it may be an 

expression that specifies computations to 
be ma d e . 

The most commonly used statement for 
internal data movement, as well as for 
specifying computations, is the assignment 
statement. The GET and PUT statements with 
the STRING option also can be used for 
internal data movement. The PUT statement 
can, in addition, specify computations to 
be made. 

The A s signment Statement 

The assignment statement, which has no 
keyword, is identified by the assignment 
symbol (=>. It generally takes one of two 

forms : 

A = B; 

A = B 4- C; 

The first form can be used purely for 
internal data movement. The value of the 
variable (or constant) to the right of the 
assignment symbol is to be assigned to the 
variable to the left. The second form 
includes an operational expression whose 
value is to be assigned to the variable to 
the left of the assignment symbol. The 
second form specifies commutations to be 
made, as well as data movement. 

Since the attributes of the variable on 
the left may differ from the attributes of 
the result of the expression (or of the 
variable or constant) , the assignment 
statement can also be used for conversion 
and editing. 



The variable on the left may be the name 
of an array or a structure; the expression 
en the right may yield an array or struc- 
ture value. Thus the assignment statement 
can be used to move aggregates of data, as 
well as single items. 



Multiple Assignment 

The value of the expression in an as- 
signment statement can be assigned to more 
than one variable in a statement of the 
following form: 



A,X 



B + C; 



Such a statement is executed in exactly the 
same way as a single assignment, except 
that the value of B + C is assigned to both 
A and X. In general, it has the same 
effect as if the following two statements 
had been written: 



A = B 

X = B 



♦ C; 
+ C; 



Note : If multiple assignment is used for a 
structure assignment BY NAME, the elemen- 
tary names affected will be only those that 
are common to all of the structures listed 
to the left of the assignment symbol. 

The STRING Option 

If the STRING option appears in a GET or 
PUT statement in place of a FILE option, 
execution of the statement will result only 
in internal data movement; neither input 
nor output is involved. 

Assume that NAME is a string of 30 
characters and that FIRST, MIDDLE, and LAST 
are string variables. Consider the follow- 
ing example: 

GET STRING (NAME) EDIT 

(FIRST r MIDDLE, LAST) 
(A(12) r Ml) # A(17>); 

This statement specifies that the first 12 
characters of NAME are to be assigned to 
FIRST, the next character to MIDDLE, and 
the remaining 17 characters to LAST. 

The PUT statement with the string option 
specifies the reverse operation, that is, 
that the values of the specified variables 
are to be concatenated into a string and 
assigned as the value of the string named 
in the STRING option. For example: 

PUT STRING (NAME) EDIT 

(FIRST, MIDDLE, LAST) 
(A(12) ,A(1) ,A(17)) ; 

This statement specifies that the values of 
FIRST, MIDDLE, and LAST are to be conca- 
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tenated, in that order, and assigned to the 
string variable NAME. 

Computations to be performed can be spe- 
cified in a PUT statement by including 
operational expressions in the data list. 
Assume, for the following example, that the 
variables A, B, and C represent arithmetic 
data and BUFFER represents a character 
string: 

PUT STRING (BUFFER) LIST (A*3,B+C) f * 

This statement specifies that the character 
string assigned to BUFFER is to consist of 
the character representations of the value 
of A multiplied by 3 and the value of the 
sum of B and C. 

Operational expressions in the data list 
of a PUT statement are not limited to PUT 
statements with the STRING option. Opera- 
tional expressions can appear in PUT state- 
ments that specify output to a file. 



PROGRAM STRUCTURE STATEMENTS 

The program structure statements are 
those statements used to delimit sections 
of a program into blocks and groups, and to 
control the allocation of storage within a 
program. These statements are the PROCE- 
DURE statement, the END statement, the 
ENTRY statement, the BEGIN statement, the 
DO statement, the ALLOCATE statement, and 
the FREE statement. The concept of blocks 
and groups is fundamental to a proper un- 
derstanding of PL/I and is dealt with in 
detail in Sections 6, 7, and 12 in Part I. 
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The PROCEDURE Statement 



Communication between two procedures is 
by means of arguments passed from an invok- 
ing procedure to the invoked procedure, by 
a value returned from an invoked procedure, 
and by names known within both procedures. 
A procedure may therefore operate upon dif- 
ferent data when it is invoked from dif- 
ferent points. A value is returned from a 
function procedure to a function reference 
by means of the RETURN statement. 



The ENTRY Statement 

The ENTRY statement is used to provide 
an alternate entry point to a procedure 
and, possibly, an alternate parameter list 
to which arguments can be passed, corre- 
sponding to that entry point. 

Note : It is important to distinguish 
between the ENTRY statement, which speci- 
fies an entry to the procedure in which it 
occurs, and the ENTRY attribute specifica- 
tion, which describes the attributes of 
parameters of procedures that are invoked 
from the procedure in which the ENTRY 
attribute specification appears. 



The principal function of a procedure 
block, which is delimited by a PROCEDURE 
statement and an associated END statement, 
is to define a sequence of operations to be 
performed upon specified data. This 
sequence of operations is given a name (the 
label of the PROCEDURE statement) and can 
be invoked from any point at which the name 
is known. 

Every program must have at least one 
PROCEDURE statement and one END statement. 
A program may consist of a number of sepa- 
rately written procedures link d together. 
A procedure may also contain other proce- 
dures nested within it. These internal 



The BFGIN Statement 

Local definitions of names can also be 
trade within begin blocks, which are delimi- 
ted by a BEGIN statement and an associated 
END statement. Begin blocks, however, are 
executed in the normal flow of a program, 
either sequentially or as a result of a GO 
TO or an IF statement transfer. One of the 
most common uses of a begin block is as the 
on-unit of an ON statement, in which case 
it is not executed through normal flow of 
control, but only upon occurrence of the 
specified condition. It is also useful for 
delimiting a section of a program in which 
some automatic storage is to be allocated. 
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Each begin block must be nested within a 
procedure or another begin block* 

The EUD Stat eme nt 

The END statement is used to signify the 
tiid of a block or group. Every block or 
(j roup must have an END statement. However, 
the END statement may be explicit or impli- 
cit; a single END statement can be applied 
to a number of nested blocks and groups by 
the inclusion of the label of the contain- 
ing block or group after the keyword END. 
r lhe other END statements are then implied 
by the one containing the label, and need 
nor be given explicitly. If no label fol- 
lows END, the secitement applies to only one 
group or block. (Multiple closure is dis- 
cussed in more detail in Section 6, 
"Blocks, Flow of Control, and Storage 
Allocation* * ) 

Execution of an END statement for a 
biocx terminates the block. However, it is 
not the only means of terminating a block, 
even though each block must have an END 
statement. For example, a procedure can be 
terminated by execution of a RETURN state- 
ment (see "Control Statements, 1 " below). 

The effect of execution of an END state- 
ment for a group depends on whether or not 
the group is iterative. If the group is 
,i I e t a t i ve r ex ec ut ion of t he EN D stateme n t 
causes control to return to the beginning 
of the group until all iterations are com- 
pleter unless control is passed out of the 
group before then. (See "Control State- 
ments," below.) If the group is nonitera- 
tive, the END statement merely delimits the 
group Cto enable the group to be treated as 
a single statement) , and control passes to 
the next statement. 

2M_ ALLOCATE and FREE Statements 

As with many other conventions in PL/I, 
rhe convention concerning storage alloca- 
tion and the scope of definitions of names 
can be overridden by the user. The storage 
class attribute AUTOMATIC is assumed for 
most variables- However a variable can be 
declared STATIC, in which case it is allo- 
cated throughout the entire program; or it 
can be declared CONTROLLED, or BASED, in 
which case its allocation can be explicitly 
specified by the user. 



The ALLOCATE s 
storage to contro 
pendent of block 
controlled arrays 
trolled strings, 
values, may also 
the ALLOCATE stat 
FREE statement is 
and based storage 
allocated. 



tatement is used to assign 
lied and based data, 5 nde- 
boundaries. The bounds of 

and the length of con- 
as well as their initial 
be specified at the time 
ement is executed. The 

used to free controlled 

after it has been 



PREPROCESSOR STATEMENTS 

PL/ I allows a degree of control over the 
contents of the source program during the 
compilation. The programmer can specify, 
for example, that any identifier appearing 
in the source program will be changed; he 
can select parts of the program to be com- 
piled without the rest; he can include text 
from an external source. These operations 
are performed by the preprocessor stage of 
the compiler, and are specified by prepro- 
cessor statements that appear among the 
other statements within the source program 
itself. 

In general, preprocessor statements are 
identified by a leading percent symbol 
before the keyword; several of them have 
the same keyword as standard PL/I state- 
ments, and these have a similar effect at 
compile-time to that of their counterpart 
at execution time. 

The complete list of preprocessor state- 
ments is : 



% 


ACTIVATE 


% 


assignment 


% 


DEACTIVATE 


% 


DECLARE 


% 


DO 


% 


END 


% 


GO TO 


% 


IF 


% 


INCLUDE 


% 


null 


% 


PROCEDURE 


RETURN 



These statements are discussed in Part I, 
Section 15, "Compile -Time Facilities," and 
in Part II, Section 10, "Statements." 



CONTROL STATEMENTS 

Statements in a PL/I program, in gener- 
al, are executed sequentially unless the 
flow of control is modified by the occur- 
rence of an interruption or the execution 
cf one of the following control statements: 

GO TO 

IF 

DO 

CALL 

RETURN 

END 

STOP 

EXIT 

The GO TO Statement 

The GO TO statement is most frequently 
used as an unconditional branch. If the 
destination of the GO TO is specified by a 
label variable, it may then be used as a 
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switch by assigning label constants, as 
values, to the label variable. 

If the label variable is subscripted, 
the switch may be controlled by varying the 
subscript. Since multidimensional label 
arrays are allowed^ and since logical 
values may be used as subscripts, quite 
subtle switching can be effected. It is 
usually true, however, that simple control 
statements are the most efficient. 

The keyword of the GO TO statement may 
be written either as two words separated by 
a blank or as a single word, GOTO. 



The IF Statement 

The IF statement provides the most com- 
mon conditional branch and is usually used 
with a simple comparison expression follow- 
ing the word IF. For example: 

IF A = B 

THEN action-if -true 
ELSE action- if-false 

If the comparison is true, the THEN 
clause (the "action to be taken") is 
executed. After execution of the THEN 
clause, control branches around the ELSE 
clause (the "alternate action"), and execu- 
tion continues with the next statement. 
Note that the THEN clause can contain a GO 
TO statement or some other control state- 
ment that would result in a different 
transfer of control. 

If the comparison is not true, control 
branches around the THEN clause, and the 
ELSE clause is executed. Control then con- 
tinues normally. 

The IF statement might be as follows: 

IF A = B 

THEN C = D; 
ELSE C = E; 

If A is equal to B, the value of D is 
assigned to c, and control branches around 
the ELSE clause. If A is not equal to B, 
control branches around the THEN clause, 
and the value of E is assigned to C. 

Either the THEN clause or the ELSE 
clause can contain some other control 
statement that causes a branch, either con- 
ditional or unconditional. If the THEN 
clause contains a GO TO statement, for 
example, there is no need to specify an 
ELSE clause. Consider the following 
exampl e : 

IF A = B 

THEN GO TO LABEL_1 ; 
next -statement 



If A is equal to B, the GO TO statement of 
the THEN clause causes an unconditional 
branch to LABEL_1. If A is not equal to B, 
control branches around the THEN clause to 
the next statement, whether or not it is an 
ELSE clause associated with the IF 
statement. 



Note: 



If the THEN clause does not cause a 



transfer of control and if it is not fol- 
lowed by an ELSE clause, the next statement 
will be executed whether or not the THEN 
clause is executed. 

The expression following the IF keyword 
can be only an element expression; it can- 
not be an array or structure expression. 
It can, however, be a logical expression 
with more than one operator. For example: 

IFA=BSC=D 
THEN GO TO R; 

The same kind of test could be made with 
nested IF statements. The following three 
examples are equivalent: 

IFA=B6C=D 
THEN GO TO R; 
B = B + 1; 





IF 


A = B 

THEN IF C = 


D 










THEN GO TO R; 




B = 


= B + 1; 










IF 


A -»= B THEN 


GO 


TO 


S; 




IF 


C -,= D THEN 


GO 


TO 


S; 




GO 


TO R; 








S: 


B 


= B ♦ 1; 








The 


DO Statement 









The most common use of the DO statement 
is to specify that a group of statements is 
to be executed a stated number of times 
while a control variable is incremented 
each time through the loop. Such a group 
might take the form: 

DO I = 1 TO 10; 



END; 

The statements to be executed iteratively 
must be delimited by the DO statement and 
an associated END statement. In this case, 
the group of statements will be executed 
ten times, while the value of the control 
variable I ranges from 1 through 10. The 
effect of the DO and END statements would 
be the same as the following: 

I = 1; 

A: IF I > 10 THEN GO TO B; 
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I = 1*1; 

GO TO A; 
B: next statement 

Note that the increment is made before the 
control variable is tested and that, in 
general, control goes to the statement fol- 
lowing the group only when the value of the 
control variable exceeds the limit set in 
the DO statement. If a reference is made 
to a control variable after the last itera- 
tion is completed, the value of the vari- 
able will be one increment beyond the spe- 
cified limit. 

The DO statement can also be used with 
the WHILE option and no control variable, 
as follows: 

DO WHILE (A = B) ; 

This statement, heading a group, causes the 
group to be executed repeatedly so long as 
the value of A remains equal to the value 

of B. 

The WHILE option can be combined with a 
control variable of the form: 

DO I = 1 TO 10 WHILE (A = B> ; 



within the DO-group* so that each iteration 
deals with successive elements of a table 
or array. For example* 

DO I = 1 TO 10; 
A(I> = I; 

END; 

In this example, the first ten elements of 
A are set to 1,2, ..•,10, respectively. 

The increment in the iteration specifi- 
cation is assumed to be one unless some 
other value is stated, as follows: 

DO I = 2 TC 10 BY 2; 

This specifies that the loop is to be 
executed five times, with the value of I 
equal to 2 , <4 , 6, 8, and 10. 

Noniterative DO Statements 

The DO statement need not specify 
repeated execution of the statements of a 
DO- group. A simple DO statement, in con- 
junction with a DO-group, can be used as 
follows: 



DO; 



This statement specifies two tests. Each 
time that I is incremented, a test is made 
to see that I has not exceeded 10. An 
additional test then is made to see that A 
is equal to B. Only if both conditions are 
satisfied will the statements of the group 
be executed. 

More than one successive iteration spe- 
cification can be included in a single DO 
statement. Consider each of the following 
DO statements : 

DO I = 1 TO 10, 13 TO 15; 

DO I = 1 TO 10, 11 WHILE (A = B) ; 

The first statement specifies that the DO 
group is to be executed a total of thirteen 
times, ten times with the value of I equal 
to 1 through 10, and three times with the 
value of I equal to 13 through 15. The 
second DO statement specifies that the 
group is to be executed at least ten times, 
and then (provided that A is equal to B) 
once more; if "BY 0" were inserted after 
"11", execution would continue with I set 
to 11 as long as A remained equal to B. 
Note that in both statements a comma is 
used to separate the two specifications. 
This indicates that a succeeding specifica- 
tion is to be considered only after the 
preceding specification has been satisfied. 

The control variable of a DO statement 
can be used as a subscript in statements 



END; 

The use of the simple Do statement in this 
manner merely indicates that the DO-group 
is to be treated logically as a single 
statement. It can be used to specify a 
number of statements to be executed in the 
THEN clause or the ELSE clause of an IF 
statement, thus maintaining sequential con- 
trol without the use of a begin block. 
(Only a single statement, a DO-group, or a 
begin block can be specified in the THEN 
clause or in the ELSE clause.) 

The CALL, RETURN, and END Statements 

A subroutine may be invoked by a CALL 
statement that names an entry point of the 
subroutine. Control is returned to the 
activating, or invoking, procedure when a 
RETURN statement is executed in the subrou- 
tine or when execution of the END statement 
terminates the subroutine. 

The RETURN statement with a parenthe- 
sized expression is used in a function pro- 
cedure to return a value to a function 
reference. This form is used to return a 
value from a procedure that has been 
invoked by a function reference. 

Normal termination of a program occurs 
as the result of execution of the final END 
statement of the main procedure or of a 
RETURN statement in the main procedure. 
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either of which returns control to the 
system. 



Note: 



A CALL statement must not contain a 



multitasking option if any part of the pro- 
gram containing the CALL statement is to be 
executed on TSS/360. 

The STOP and EXIT Statements 

The STOP and EXIT statements are both 
used to cause termination of execution and 
return of control to the command system. 



EXCEPTION CONTROL STATEMENTS 

The control statements, discussed in the 
preceding section, alter the flow of con- 
trol whenever they are executed. Another 
way in which the sequence of execution can 
be altered is by the occurrence of a pro- 
gram interruption caused by an exceptional 
condition that arises. 

In general, an exceptional condition is 
the occurrence of an unexpected action, 
such as an overflow error, or of an 
expected action, such as an end of file, 
that occurs at an unpredictable time. A 
detailed discussion of the handling of 
these conditions appears in Part I, Section 
13, "Exceptional Condition Handling and 
Program Checkout.* 

The three exception control statements 
are the ON statement, the REVERT statement, 
and the SIGNAL statement. 



This statement specifies that when an 
interruption occurs as the result of trying 
to read beyond the end of the file named 
DETAIL, control is to be transferred to the 
statement labeled NEXT^MASTER. 

When execution of an on-unit is success- 
fully completed, control will normally 
return to the point of the interruption or 
to a point immediately following it, 
depending upon the condition that caused 
the interruption. 

An important use of the ON statement is 
for debugging. The CHECK condition causes 
debugging information to be printed whenev- 
er the value of one of a list of specified 
variables is changed or whenever a speci- 
fied statement is executed. 

The effect of an ON statement, the es- 
tablishment of the on-unit, can be changed 
within a block (1) by execution of another 
ON statement naming the same condition with 
either another on-unit or the word SYSTEM, 
which reestablishes standard system action, 
or (2) by the execution of a REVERT state- 
ment naming that condition. On-units in 
effect at the time another block is acti- 
vated remain in effect in the activated 
block, and in other blocks activated by it, 
unless another ON statement for the same 
condition is executed. When control 
returns to an activating block, on-units 
are reestablished as they existed. 



The REVERT Statement 



The ON Statement 

The ON statement is used to specify 
action to be taken when any subsequent 
occurrence of a specified condition causes 
a program interruption. ON statements may % 
specify particular action for any of a 
number of different conditions. For all of 
these conditions, a standard system action 
exists as a part of PL/I, and if no ON 
statement is in force at the time an inter- 
ruption occurs, the standard system action 
will take place. For most conditions, the 
standard system action is to print a mes- 
sage and terminate execution. 

The ON statement takes the form: 

ON condition- name (SYSTEM; | on- unit) 

The "condition name" is one of the keywords 
listed in Part II, Section 8, "ON- 
Conditions." The "on-unit" is a single 
statement or a begin block that specifies 
action to be taken when that condition 
arises and an interruption ceurs. For 
example: 

ON ENDFILEC DETAIL) GO TO NEXT_MASTER; 



The REVERT statement is used to cancel 
the effect of all ON statement:; for the 
same condition that have been executed in 
the block in which the REVERT statement 
appears . 

The REVERT statement, which must specify 
the condition naire, reestablishes the on- 
unit that was in effect in the activating 
block at the time the current block was 
invoked. 



1 he SIGNAL Statement 

The SIGNAL statement simulates the 
occurrence of an interruption for a named 
condition. It can be used to test the cod- 
ing of the on-unit established by execution 

cf an ON statement. For example: 

SIGNAL OVERFLOW; 

This statement would simulate the occur- 
rence of an overflow interruption and would 

cause execution of the on-unit established 
for the OVERFLOW condition. If an on-unit 
has not teen established, standard system 
action is taken. 
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SECTION 6; BLOCKS, FLOW OF CONTROL, AND STORAGE ALLOCATION 



This section discusses how statements 
can be organized into blocks to form a PL/I 
program, how control flows within a program 
from one block of statements to another, 
and how storage may be allocated for data 
within a block of statements. 



A PL/I program consists of one or more 
such procedures, each of which may contain 
other procedures and/or begin blocks. 



BEGIN BLOCKS 



BLOCKS 

A block is a delimited sequence of 
statements that constitutes a section of a 
program. It localizes names declared 
within the block and limits the allocation 
of variables. There are two kinds of 
blocks s procedure blocks and begin blocks. 



PROCEDURE BLOCKS 

A procedure block, simply called a pro- 
cedure, is a sequence of statements headed 
by a PROCEDURE statement and ended by an 
END statement, as follows: 

label: [label:]... PROCEDURE; 



END [label] ; 

All procedures must be named because the 
procedure name is the primary point of 
entry through which control can be trans- 
ferred to a procedure. Hence, a PROCEDURE 
statement must have at least one label. A 
label need not appear after the keyword END 
in the END statement, but if one does 
appear, it must match the label (or one of 
the labels) of the PROCEDURE statement to 
which the END statement corresponds. 
(There are exceptions; see "Use of the END 
Statement with Nested Blocks and DO-Groups" 
in this chapter. > An example of a 
procedure: 



READIN: 



PROCEDURE 

statement-1 

statement-2 



statement-n 
END READIN; 



In general, control is transferred to a 
procedure through a reference to the name 
(or one of the names) of the procedure. 
Thus, the procedure in the above example 
would be given control by a reference to 
either of its names, A or READIN. 



A begin block is a set of statements 
headed by a BEGIN statement and ended by an 
END statement, as follows: 

(label: 1 . .. BEGIN; 



END (label!; 

Unlike a procedure block, a label is 
optional for a begin block. If one or more 
labels are prefixed to a BEGIN statement, 
they serve only to identify the starting 
point of the block. (Control may pass to a 
begin block without reference to the name 
of that block through normal sequential 
execution, although control can be trans- 
ferred to a labeled BEGIN statement by 
execution of a GO TO statement.) The label 
following END is optional. However, a 
label can appear after END, matching a 
label of the corresponding BEGIN statement. 
(There are exceptions; see "Use of the END 
Statement with Nested Blocks and DO-Groups w 
in this chapter. ) An example of a begin 
block: 



B: CONTROL: 



BEGIN; 

statement-1 

statement-2 



statement-n 
END B; 



Unlike procedures, beqin blocks general- 
ly are not given control through special 
references to them. The normal sequence of 
control governing ordinary statement execu- 
tion also governs the execution of begin 
blocks. Control passes into a begin block 
sequentially, following execution of the 
preceding statement. 

Begin blocks are not essential to the 
construction of a PL/I program. However, 
there are times when it is advantageous to 
use begin blocks to delimit certain areas 
of a program. These advantages are dis- 
cussed in this section and in Part I ff Sec- 
tion 7, "Recognition of Names." 
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INTERNAL AND EXTERNAL BLOCKS 

Any block can contain one or more 
blocks. That is, a procedure, as well as a 
begin block, can contain other procedures 
and begin blocks. However, there can be no 
overlapping of blocks; a block that con- 
tains another block roust totally encompass 
that block. 

A procedure block that is contained 
within another block is called an internal 
procedure . A procedure block that is not 
contained within another block is called an 
external procedure . There roust always be 
at least one external procedure in a PL/I . 
program. (Note: With System/360 implemen- 
tations, each external procedure is com- 
piled separately. Entry names of external 
procedures cannot exceed seven characters.) 

Begin blocks are always internal? they 
must always be contained within another 
block. 

Internal procedure and begin blocks can 
also be referred to as nested blocks . 
Nested blocks, in turn, may have blocks 
nested within them, and so on. The outer- 
most block always must be a procedure. 
Consider the following example: 

A: PROCEDURE; 

statement-al 
statement-a2 
statement- a 3 
B: BEGIN; 

statement- bl 
statement-b2 
statement~b3 
END B; 
statement- a4 
statement-a5 
C: PROCEDURE; 
statement-cl 
statement-c2 
D: BEGIN; 

statement-dl 
stateroent-d2 
statement-d3 
E: PROCEDURE; 
statement-el 
statement-e2 
END E; 
stateraent-d4 
END B; 
END C; 
statement-a6 
statement-a7 
END A; 

In the above example, procedure block A 
is an external procedure because it is not 
contained in any other block. Blcck B is a 
begin block that is contained in A; it con- 
tains no other blocks. Block J is an 
internal procedure; it contains begin block 
D, which, in turn, contains internal proce- 



dure E- This example contains three levels 

cf nesting relative to A? B and C are at 
the first level, D is at the second level 
(but the first level relative to C) and E 
is at the third level (the second level 
relative to C, and the first level relative 
to D). 

There must not be more than 50 levels of 
nesting at any point in the compilation. 
The degree of nesting at any point is the 

number of PROCEDURE, BEGIN, or DO state- 
ments without a corresponding END state- 
ment, plus the number of currently active 
IF compound statements , plus the number cf 
■currently unmatched left parentheses, plus 
the number of dimensions in each active 
array expression, plus the maximum number 
cf dimensions in each active array expres- 
sion, plus the maximum number of dimensions 
in each active structure expression. 

Use of the END Statement With Nested Blocks 
and CO-Groups (Multiple Closure) 



The use of the END statement with a 
cedure, begin block, or DO-group is 
governed by the following rules: 



pro- 



1. If a label is not used after END* the 
END statement closes (i.e., ends) that 

unclosed block headed by the BEGIN or 
PROCEDURE statement, or that unclosed 
DO-group headed by the DO statement, 

that physically precedes, and appears 
closest to, the END statement. 

2. If the optional label is used after 
END, the END statement closes that 
unclosed block or DO-group headed by 
the BEGIN, PROCEDURE, or DO statement 
that has a matching label, and that 
physically precedes, and appears clos- 
est to, the END statement. Any 
unclosed blocks or DO-groups nested 
within such a block or DO-group are 
automatically closed by this END 
statement; this is known as multiple 
closu re. 

From the second rule, it is evident that 
nested blocks sometimes make it possible 
for 3 single END statement to close more 
than one block. For example, assuie that 
the following external procedure has been 
defined: 

FRST: PROCEDURE; 

statement-f 1 
statement- f 2 
ABLK: BEGIN; 

statement- al 

statement -a 2 
SCND: PROCEDURE? 
statement- si 
BBLK: BEGIN; 

statement- bl 
END; 
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END; 
statement -a 3 
END ABLK; 
END FRST; 

In this example, begin block BBLK and 
internal procedure SCND effectively end in 
the same place; that is, there are no 
statements between the END statements for 
each. This is also true for begin block 
ABLK and external procedure FRST. In such 
cases, it is not necessary to use an END 
statement for each block, as shown; rather, 
one END statement can be used to end BBLK 
and SCND, and another END can be used to 
end ABLK and FRST. In the first case, the 
statement would be END SCND, because one 
END statement with no following label would 
close only the begin block BBLK (see the 
first rule above). In the second case, 
only the statement END FRST is required; 
the statement END ABLK is superfluous. 
Thus, the example could be specified as 
follows ; 



the same role in the allocation and freeing 
of storage, as well as in delimiting the 
scope of names, they differ in the way they 
are activated and executed. A begin block, 
like a single statement, is activated and 
executed in the course of normal sequential 
program flow (except when specified as an 
on-unit) and, in general, can appear 
wherever a single statement can appear. 
For a procedure, however, normal sequential 
program flow passes around the procedure, 
from the statement before the PROCEDURE 
statement to the statement after the END 
statement of that procedure. The only way 
in which a procedure can be activated is by 
a procedure reference . 



A procedure reference is the appearance 
of an entry name (defined below) in one of 
the following contexts : 

1. After the keyword CALL in a CALL 
statement 



FRST ; PROC EDURE ; 

statement-! 1 
statement-f 2 
ABLK; BEGIN; 

stateraent-al 
statement-a2 
SCND: PROCEDURE; 

statement~sl 
statement-s2 
BBLK: BEGIN; 

statement-bl 
statement- b2 
END SCND; 
statement-a3 
END FRST; 



2. After the keyword CALL in the CALL 
option of the INITIAL attribute (see 
the discussion of the INITIAL attri- 
bute in Part II, Section 9, "Attri- 
butes," for details) 

3. As a function reference (see Part I, 
Section 12, "Subroutines and Func- 
tions," for details) 

This chapter uses examples of the first 
of these; that is, with the procedure 
reference of the form: 

CALL entry-name; 



Note the following example: 

CBLK: PROCEDURE; 

statement-cl 

statement-c2 
DGP: DO I = 1 TO 10; 

statement-dl 

GO TO LBL; 

statement-d2 
LBL: END CBLK; 

In this example, the END CBLK statement 
closes the block CBLK and the iterative 
DO-group DGP. The effect is as if an un- 
labeled END statement for DGP appeared 
immediately after statement-d2, so that the 
transfer to LBL would prevent all but the 
first iteration of DGP from taking place, 
and statement-d2 would not be executed. 



The material, however, is relevant to the 
other two forms as well. 

An entry name is defined as either of 
the following: 

1. The label, or one of the labels, of a 
PROCEDURE statement 

2. The label, or one of the labels, of an 

ENTRY statement appearing within a 
procedure 

The first of these is called the pr intarv 
entry point to a procedure; the second is 
known as a secondary entry point tc a pro- 
cedure. The following is an example of a 
procedure containing secondary entry 
points: 



ACTIVATION AN D TERMINATION OF BLOCKS 

ACTIVATION 

Although the begin block and the proce- 
dure have a physical resemblance and play 



ERRT: 



PROCEDURE; 
statement-1 
statement- 2 
ENTRY; 
statement- 3 
statement-** 
statement- 5 
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NEXT: RETR: ENTRY; 

statement-6 
statement- 7 

statement-8 
END A; 



In this example, A is the primary entry 
point to the procedure, and ERRT, NEXT, and 
RETR specify secondary entry points. Actu- 
ally, since they are both labels of the 
same ENTRY statement, NEXT and RETR specify 
the same secondary entry point. 

When a procedure reference is executed, 
the procedure containing the specified 
entry point is activated and is said to be 
invoked ; control is transferred to the 
specified entry point. The point at which 
the procedure reference appears is called 
the point of invocation and the block in 
which the reference is made is called the 
invoking block . An invoking block remains 
active even though control is transferred 
from it to the block it invokes. 

Whenever a procedure is invoked at its 
primary entry point, execution begins with 
the first executable statement in the 
invoked procedure. However, when a proce- 
dure is invoked at a secondary entry point, 
execution begins with the first executable 
statement following the ENTRY statement 
that defines that secondary €>ntry point. 
Therefore, if all of the numbered state- 
ments in the last example are executable, 
the statement CALL A would invoke procedure 
A at its primary entry point, and execution 
would begin with statement-1; the statement 
CALL ERRT would invoke procedure A at the 
secondary entry point ERRT, and execution 
would begin with statement-3; either of the 
statements CALL NEXT or CALL RETR would 
invoke procedure A at its other secondary 
entry point, and execution would begin with 
statement-6. Note that any ENTRY state- 
ments encountered during sequential flow 
are never executed; control flows around 
the ENTRY statement as though the statement 
were a comment. 

Any procedure, whether external or 
internal, can always invoke an external 
procedure, but it cannot always invoke an 
internal procedure that is contained in 
some other procedure. Those internal pro- 
cedures that are at the first level of 
nesting relative to a containing procedure 
can always be invoked by that containing 
procedure, or by each other. For example: 

PRMAIN: PROCEDURE; 
stat erne nt-1 
statement- 2 
statement- 3 
A: PROCEDURE; 

statement-al 

statement-a2 



B: PROCEDURE; 
statement- bl 
statement-b2 

END A; 
stateraent-4 
statement- 5 
C: PROCEDURE; 

statement-cl 

statement-c2 

END C; 
statement-6 
statement-7 
END PRMAIN; 



In this example, PRMAIN can invoke pro- 
cedures A and C, but not B; procedure A can 
invoke procedures B and C; procedure B can 
invoke procedure C; and procedure C can 
invoke procedure A but not B. 



The foregoing discussion about the acti- 
vation of blocks presupposes that a program 
has already been activated. A PL/I program 
becomes active when a calling prograir 
invokes the initial procedure . This call- 
ing program usually is the time-sharing 
system, although it could be another pro- 
gram. For System/36 implementations, the 
initial procedure, called the main proce- 
dure, must be an external procedure whose 
PROCEDURE statement has the OPTIONS (WAIN) 
specification, as shown in the following 
example: 



CONTRL: PROCEDURE OPTIONS (MAIN) ; 
CALL A; 
CALL B; 
CALL C; 
END CONTRL; 

In this example, CONTRL is the initial pro- 
cedure and it invokes other procedures in 
the program. 

The following is a summary of the acti- 
vation of blocks: 

• A program becomes active when the ini- 
tial procedure is activated by the 

system. 

• Except for the initial procedure, 
external and internal procedures con- 
tained in a program are activated only 
when they are invoked by a procedure 
reference. 

• Begin blocks are activated through 
normal sequential flow or as on-units. 

• The initial procedure remains active 
for the duration of the program. 

• All activated blocks remain active 
until they are terminated (see below). 
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TERMINATION 

In general, a procedure block 
ruinated when, by some means othe 
procedure reference, control pas 
the invoking block or to some ot 
block. Similarly, a begin block 
minated when, by some weans othe 
procedure reference, control pas 
another active block. There are 
of ways by which such transfers 
can be accomplished, and their i 
tions differ according to the ty 
being terminated. 



is ter- 
r than a 
ses back to 
her active 

is ter- 
r than a 
ses to 

a number 
of control 
nterpreta- 
pe of block 



Begin Block Termination 

A begin block is terminated when any of 
the following occurs : 

1. Control reaches the END statement for 
the block. When this occurs, control 
moves to the statement physically fol- 
lowing the END, except when the block 
is an on-unit. 

2. The execution of a GO TO statement 
within the begin block (or any block 
activated from within that begin 
block) transfers control to a point 
not contained within the block. 

3. A STOP or EXIT statement is executed 
(thereby terminating execution). 

4. Control reaches a RETURN statement 
that transfers control out of the 
begin block and out of its containing 
procedure as well. 

A GO TO statement of the type described 
in item 2 can also cause the termination of 
other blocks as follows; 

If the transfer point is contained in a 
block that did not directly activate the 
block being terminated, all intervening 
blocks in the activation sequence are 
terminated. 

For example, if begin block B is con- 
tained in begin block A, then a GO TO 
statement in E that transfers control to a 
point contained in neither A nor B effec- 
tively terminates both A and B. This case 
is illustrated below: 

FRST: PROCEDURE OPTIONS (MAIN) ? 
statement- 1 
statement-2 
statement-3 
A: BEGIN; 

statement-al 
statement-a2 
B: BEGIN; 

statement-bl 
statement-b2 



LAB: 



GO TO LAB; 
statement~b3 

END B; 
statement-a3 

END A; 
statement- 4 
statement-S 
statement-6 
statercent-7 
END FRST; 



After FRST is invoked, the first three 
statements are executed and then begin 
block A is activated. The first two state- 
ments in A are executed and then begin 
block B is activated (A remaining active), 
fthen the GO TO statement in B is executed, 
control passes to statement-6 in FRST. 
Since statement-6 is contained in neither A 
nor B, both A and B are terminated. Thus, 
the transfer of control out of begin block 
B results in the termination of intervening 
block A as well as termination of block B. 

Procedure Termination 

A procedure is terminated when one of 
the following occurs: 

1. Control reaches a RETURN statement 
within the procedure. The execution 
of a RETURN statement causes control 
to be returned to the point of invoca- 
tion in the invoking procedure. If 
the point of invocation is a CALL 
statement, execution in the invoking 
procedure resumes with the statement 
following the CALL. If the point of 
invocation is one of the other forms 
of procedure references (that is, a 
CALL option or a function reference), 
execution of the statement containing 
the reference will be resumed. 

2. Control reaches the END statement of 
the procedure. Effectively, this is 
equivalent to the execution of a 
RETURN statement. 

3. The execution of a GO TO statement 
within the procedure (or any block 
activated from within that procedure) 
transfers control to a point not con- 
tained within the procedure. 

4. A STOP or EXIT statement is executed 

(thereby terminating execution). 

Items 1 # 2, and 3 are normal procedure 
terminations; item *f is abnormal procedure 
termination. 

As with a begin block, the type of ter- 
mination described in item 3 can sometimes 
result in the termination of several proce- 
dures and/or begin blocks. Specifically, 
if the transfer point specified by the GO 
TO statement is contained in a block that 
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did not directly activate the block being 
terminated, ail intervening blocks in the 
activation sequence are terminated. Con- 
sider the following example: 

A; PROCEDURE OPTIONS (MAIN) ; 
statement-1 
statement -2 

B: BEGIN; 

statement-bl 
statement- b2 
CALL C; 
statement- b3 
END B; 
statement- 3 
statement-** 
C: PROCEDURE; 
statement-cl 
statement-c2 
statement-c3 
D: BEGIN; 

statement-dl 
statement- d2 
GO TO LAB; 
statement-d3 
END D; 
statement- c4 
END C; 
statement -5 
LAB: statement-6 
statement-7 
END A; 

In the above example, A activates B f 
which activates C # which activates D. In 
D, the statement GO TO LAB transfers con- 
trol to statement-6 in A. Since this 
statement is not contained in D, C, or B f 
all three blocks are terminated; A remains 
active. Thus, the transfer of control out 
of D results in the termination of inter- 
vening blocks B and C as well as the ter- 
mination of block D. 

Program Termination 

A program is terminated when any one of 
the following occurs : 

1. Control for the program reaches an 
EXIT statement. This is abnormal 
termination. 

2. Control for the program reaches a STOP 
statement. This also is abnormal 
termination. 



Note : The termination of a program, wheth- 
er normal or abnormal , raises the FINISH 
condition. The* standard system action for 
this condition is to return control to the 
system. For normal termination, the system 
will then pass control to the calling pro- 
gram, it any. For abnormal termination, it 
will terminate? execution. (See Part II, 
Section 8, "ON-conditions." ) 



STORAGE ALLOCATION 

Storage allocation is the process of 
associating an area of storage with a vari- 
able so that the data items to be repre- 
sented by the variable may be recorded 
internally. When storage has been asso- 
ciated with a variable, the variable is 
said to be allocated . Allocation for a 
given variable may take place statically , 
that is, before the execution of the pro- 
gram, or dynamically , during execution. A 
variable that is allocated statically 
remains allocat ed while the program is 
loaded. A variable that is allocated 
dynamically relinquishes its storage either 
upon the termination of the block contain- 
ing that variable or at. the request of the 
user, depending upon its storage class. 

The manner in which storage is allocated 
for a variable is determined by the storage 
class of that variable. There are four 
storage classes: static, automatic, con- 
trolled, and based- Each storage class is 
specified by it!; corresponding storage 
class attribute: STATIC, AUTOMATIC, CON™ 
TROLLED, and BASED, respectively. The last 
three define dynamic storage allocation. 

Storage class attributes may be declared 

explicitly for element, array, and major 
structure variables. If a variable is an 
array or a major structure variable, the 

storage class declared for that variable 
applies to all of the elements in the array 
or structure. 

All v a r i a bl es t hat have not been expli- 
citly declared with a storage class attri- 
bute are assumed to have the AUTOMATIC 
attribute, with one exception: any vari- 
able that has the EXTERNAL attribute is 
assumed to have the STATIC attribute. 



Control reaches a RETURN statement or 
the final END statement in the main 
procedure. This is normal termination. 

An on-unit for the ERROR cjndition is 
executed with normal return (that is f 
a GO TO statement does not transfer 
control out of the on-unit > or the 
FINISH condition is raised as a result 
of the standard system action for the 
ERROR condition. 

Execution of a restricted function 
(for example, multitasking or REGIONAL 
I/O) is called for. 
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OUTP : PROCEDUHE ; 

DECLARE X FIXED STATIC INITIAL CD I 



PUT DATA (X); 



X = X+l; 

END OUTP; 

In the above example, the first time 
that procedure OUTP is invoked, X has the 
value 1 and execution of the PUT statement 
causes the item X=l to be written. Before 
OUTP is terminated, the assignment state- 
ment X=x*l increases the value of X by 1. 
If OUTP is invoked a second time during the 
same load, and if the value of X is not 
changed elsewhere in the program, X has the 
value 2. CX is not reinitialized to 1.) X 
would also have the value 2 if: 

# OUTP were a main procedure . 

• X were declared as an EXTERNAL static 
variable. 

When the PUT statement is executed for the 
second time, the item X=2 is written into 

the stream. 

Thus, the static variable X might be 
used to record the number of times OUTP is 
invoked. 

Automatic Storage 

A variable that has the AUTOMATIC attri- 
bute is allocated storage upon activation 
of the block in which that variable is 
declared. The variable remains allocated 
as long as the block remains active; it is 
freed when the block is terminated. Once a 
variable is freed, its value is lost. 

Controlled Storage 

A variable that has the CONTROLLED 
attribute is allocated storage only upon 
the execution of an ALLOCATE statement 
specifying that variable. Storage remains 
allocated for that variable until the 
execution of a FREE statement in which the 
variable is specified. This allocation 
remains even after termination of the block 
in which it is allocated. Thus, the allo- 
cation and freeing of storage for variables 
declared with the CONTROLLED attribute is 
directly under the control of the user. 

A controlled variable may be stacked ; 
that is, storage may be allocated for a 
controlled variable even when a previous 
allocation for that variable exists- In 
terms of ALLOCATE and FREE statements 9 
stacking occurs when an allocated con- 
trolled variable is specified in an ALLO- 
CATE statement without first having been 



specified in a FREE statement. When this 
occurs, the previous allocation is not 

released; its value remains the same but, 
for the time being, this value is not 
available to the user. Conceptually, the 
new allocation is stacked on top of the 
previous allocation, with the result that 
the previous allocation is "pushed-down" in 
the stack. Subsequent allocations are 
always added to the top of the stack. 

Any reference to a stacked controlled 
variable always refers to the most recent 
allocation for that variable, that is, to 
the allocation at the top of the stack. 
Thus, a FREE statement specifying a stacked 
controlled variable will cause the alloca- 
tion at the top of the stack to be freed. 
When this occurs, the other allocations in 
the stack are " popped- up" , the most recent 
previous allocation coming to the top and 
being availpble once again. When an allo- 
cation is popped u p to the top of a stack, 
its value is the same as it was when it war* 
pushed down . 

Based Stora ge 

Based storage is similar to controlled 
storage in that it can be allocated by the 
ALLOCATE statement and freed by the FREL 
statement; and more than one allocation can 
exist tor one variable. However, the ur.fr 
has a much greater degree of control with 
based storage. For example, all current 
based allocations are available at any 
time: unique reference to a particular 
allocation is provided by a pointer value 
qualifying the based variable reference. 

The use of based storage also allows 
data to he processed in an I/O buffer 
without it having to be moved from the 
buffer to a variable (that is, to a work 
area). By means of the LOCATE' statement 
and the READ statement with the SET option, 
the structure of the based variable is 
superimposed on the data in the output or 
input buffer respectively, so that any 
reference to that allocation of the based 
variable is a reference to that data. 

Based storage is the most powerful of 
the PL/I storage classes, but it must In 
used carefully; many of the safeguards 

against error that are provided for other 
storage classes cannot be provided for 

based. 

For full details of based storage, see 
Part I, Section 14, "Based Storage and List 
Processing. " 



REACTIVATION OF AN ACT IV E PROCEDURE 
(RECURSION) 

An active procedure that can be reacti- 
vated from within itself or from within 

another active procedure is said to be a 
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For full details of based storage, see 
Part X, Section l*l f "Based Storage and List 
Processing." 



REACTIVATION OF AN ACTIVE PROCEDURE 
(RECURSION) 

An active procedure that can be reacti- 
vated from within itself or from within 
another active procedure is said to be a 
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recursive procedure; such reactivation is 
called recursion. 



A procedure can be invoked recursively 
only if the RECURSIVE option has been spec- 
ified in its PROCEDURE statement. This 
option also applies to the names of any 
secondary entry points that the procedure 
might have. 



The environment (that is, values of 
automatic variables, etc.) of every invo- 
cation of a recursive procedure is pre- 
served in a manner analogous to the stack- 
ing of allocations of a controlled vari- 
able. An environment can thus be thought 
of as being "pushed down" at a recursive 
invocation, and "popped up" at the termina- 
tion of that invocation. Note that a label 
constant always contains information iden- 
tifying the current invocation of the block 
that contains the label. Hence, if a label 
constant is assigned to a label variable in 
a particular invocation, a GO TO statement 
naming that variable in another invocation 
could restore the environment that existed 
when the assignment was performed. 

Consider the following example: 

RECURS: PROCEDURE RECURSIVE; 

DECLARE X STATIC EXTERNAL INITIAL (0); 



X=X+1; 

PUT DATA (X); 

IF X =5 THEN GO TO LAB; 

CALL AGN; 

X =X-1; 

PUT DATA (X); 



LAB: END RECURS; 

AGN: PROCEDURE RECURSIVE; 

DECLARE X STATIC EXTERNAL INITIAL (0) ; 



X=X+1; 

PUT DATA(X); 



CALL RECURS; 
X=X-1; 

PUT DATA (X) ; 
END AGN; 

In the above example, RECURS and AGN are 
both recursive procedures . Since X is 
static and has the INITIAL att ibute, it is 
allocated and initialized before execution 
of the program begins. 



The first time that RECURS is invoked, X 
is incremented by 1 and X=l is transmitted 
fcy the PUT statement. Since X is less than 
5, AGN is invoked. In AGN f X is incre- 
mented by 1 and X=2 is transmitted (also by 
a PUT statement). AGN then reinvokes 
RECURS. 



This second 
recursive invo 
still active, 
and then X=3 i 
less than 5, s 
Since AGN is a 
invocation of 
incremented on 
and RECURS is 



invocation of RECURS is a 
cation, because RECURS is 

X is incremented as before, 
s transmitted. X is still 
o AGN is invoked again. 
ctive when invoked, this 
AGN is also recursive. X is 
ce again, X=4 is transmitted, 
invoked for the third time. 



The third invocation of RECURS results 
in the transmission of X=5 . But, since X 
is nc longer less than 5, GO TO LAB is 
executed, and then RECURS is terminated. 
However, only the third invocation of 
RECURS is terminated, with the result that" 
control returns to the procedure that 
invoked RECURS for the third time; that is, 
control returns to the statement following 
CALL RECURS in the second invocation of 
AGN. At this point X is decremented by 1 
and X=4 is transmitted. Then the second 
invocation of AGN is terminated, and con- 
trol returns to the procedure that invoked 
AGN for the second time; that is, control 
returns to the statement following CALL AGN 
in the second invocation of RECURS. Here X 
is decremented again and X~3 is trans- 
mitted, after which the second invocation 
cf RECURS is terminated and control returns 
to the first invocation of AGN. X is 
decremented again, X=2 is transmitted, the 
first invocation of AGN is terminated, and 
control returns to the first invocation of 
RECURS. X is decremented, X=l is trans- 
iritted, X is reset to # and the first 
invocation of RECURS is terminated. Con- 
trol then returns to the procedure that 
invoked RECURS in the first place. 



and 

rec 

spe 

Eve 

PL/ 

is 

dur 

exe 

dat 



Note the difference between recursive 
reenterafcl 



e procedures. A procedure is 
ursive only if the RECURSIVE option is 
cifi»ri in the PROCEDURE statement, 
ry procedure compiled by the TSS/360 
T compiler is reenterable; that is, it 
a procedure that does not modify itself 
ing its execution, so that subsequent 
cution of the procedure with the same 
a will always give the same result. 
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Allocation cf static variables (as il- 
lustrated above) is not affected by recur- 
sion, because they are allocated storage 
outside the environment of a recursive pro- 
cedure. Allocation of controlled variables 
is likewise unaffected because their allo- 
cation and release is completely under the 
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control of the user. 
of automatic variables 
they are a part of the 
particular invocation 
their allocation and r 
1/ controlled by the u 
based variables also, 
si on that the storage 
variable must be taken 



However, allocation 
is affected, because 
environment of a 
and also because 
elease is not direct- 
ser. This applies to 
but with the provi- 
class of the pointer 
into account. 



• Computing dimension bounds and string 
lengths for automatic and DEFINED 
variables and ENTRY declarations. 



• Allocating storage for automatic 
variables and initialization, if 
specified. 



Each time a procedure is invoked recur- 
sively, storage for each automatic variable 
is reallocated, and the previous allocation 
is pushed down in a stack. Each time an 
activation of a recursive procedure is ter- 
minated, automatic storage is popped up to 
yield the next most recent generation of 
automatic storage. Hence, each generation 
of automatic storage is preserved as part 
of the environment of the corresponding 
recursive activation. 

| Pointer variables, unless they are 
J explicitly declared otherwise, are automat- 
| ic by default, and are therefore subject to 
t the .stacking process described above. Con- 
i sequent! y, when reference is made to a 
| based variable in a recursive procedure, 
I the programmer should take care to ensure 
I the validity and accuracy of the pointer 
j qualifier . 



lROUjCUES AND EPILOGUES 

Each time a block is activated, certain 
activities must be performed before control 
can reach the first executable statement in 
the block. This set of activities is 
called a prologue . Similarly, when a block 
is terminated, certain activities must be 
performed before control can be transferred 
out of the block,* this set of activities is 
called an epilogu e. 

Prologues and epilogues are the respon- 
sibility of the compiler and not of the 
user. They are discussed here because 
knowledge of them may assist the user in 
improving the performance of his program. 

Prologues 

A prologue is a compiler-written routine 
logically appended to the beginning of a 
block and executed as the first step in the 
activation of a block. In general, activi- 
ties performed by a prologue are as 
follows: 



• Determining which currently active 
blocks are known to the procedure, so 
that the correct generations of auto- 
matic storage are accessible, and the 
correct cn-units may be entered* 

• Allocating storage for dummy arguments 
that may be passed from this block. 

The prologue may need to evaluate ex- 
pressions defining lengths, bounds, itera- 
tion factors, and initial values. Note 
that if an item is referred to in an ex- 
pression and the allocation or initializa- 
tion of a second item depends on that ex- 
pression, then the first item must be in no 
way dependent on the second item for its 
own allocation and initialization. Furth- 
er, the first item must be in no way depen- 
dent on any other item that so depends on 
the second item. For example, the follow- 
ing declaration is invalid: 

DCL A(BCl)) INITIAL (2), 
BCA(1>) INITIAL (3) ; 

However, the following declaration is 
valid: 

DCL N INITIAL (3) , 
ACN) , 
B CHARCN) ; 



Epilogues 

An epilogue is a compiler-written rou- 
tine logically appended to the end of a 
block and executed as the final step in the 
termination of a block. In general, the 
activities performed by an epilogue are as 
follows: 

• Reestablishing the on-unit environment 
existing before the block was 
activated. 

• Releasing storage for all automatic 
variables allocated in the block. 
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SECTION 7: RECOGNITION OF NAMES 



A PL/ 1 program consists of a collection 
of identifiers, constants, and special 
characters used as operators or delimiters. 
Identifiers themselves may be either key- 
words or names with a meaning specified by 
the user. The PL/I language is constructed 
so that the compiler can determine from 
content whether or not an identifier is a 
keyword, so there is no list of reserved 
words that must not be used for user- 
defined names- Any identifier may be used 
as a name; the only restriction is that at 
any point in a program a name can have one 
and only one meaning. For example, the 
same name cannot be used for both a file 
and a floating-point variable. 



Note : The above is true so long as the 
60-character set is used. Certain identi- 
fiers of the 4 8- character set cannot be 
used as user-defined identifiers in a pro- 
gram written using the 4 8 -character set; 
these identifiers are: GT f GE f NE f LT f NG f 
LE, NL, CAT, OR, AND, NOT f and PT. 

It is not necessary, however, for a name 
to have the same meaning throughout a pro- 
gram. A name declared within a block has a 
meaning only within that block. Outside 
the block it is unknown unless the same 
name has also been declared in the outer 
block. In this case, the name, in the outer 
block refers to a different object. This 
enables users to specify local definitions 
and, hence, to write procedures or begin 
blocks without knowing all the names being 
used by other users writing other parts of 
the program. 

Since it is possible for a name to have 
more than one meaning, it is important to 
define which part of the program a particu- 
lar meaning applies to. In PL/I a name is 
given attributes and a meaning by a 
declaration (not necessarily explicit). 
The part of the program for which the mean- 
ing applies is called the scope of the 
declaration of that name. In most cases, 
the scope of a name is determined entirely 
by the position at which the name is 
declared within the program Cor assumed to 
be declared if the declaration is not 
explicit). There are cases in which more 
than one generation of data may exist with 
the same name (such as in recursion); such 
cases are considered separately. 

In order to understand the rules for the 
scope of a name, it is necessary to under- 
stand the terms "contained in* and •intern- 
al to. • 



Contained In : All of the text of a block, 
from the PROCEDURE or BEGIN statement 
through the corresponding END statement, is 
said to be contained in that block. Note, 
however, that the labels of the BEGIN or 
PROCEDURE statement heading the block, as 
well as the labels of any ENTRY statements 
that apply to the block, are not contained 
in that block. Nested blocks are contained 
in the block in which they appear. 

Internal To : Text that is contained in a 
block, but not contained in any other block 
nested within it, is said to be internal to 
that block. Note that entry names of a 
procedure (and labels of a BEGIN statement) 
are not contained in that block. Conse- 
quently, they are internal to the contain- 
ing block. Entry names of an external pro- 
cedure are treated as if they were external 
to the external procedure. 

In addition to these terms, the dif- 
ferent types of declaration are important. 
The three different types — explicit 
declaration, contextual declaration, and 
implicit declaration — are discussed in 
the following sections. 



EXPLICIT DECLARATION 

A name is explicitly declared if it 
appears: 

1. In a DECLARE statement 

2. In a parameter list 

3. As a statement label 

4. As a label of a PROCEDURE or ENTRY 
statement 

The appearance of a name in a parameter 
list is the same as if a DECLARE statement 
for that name appeared immediately follow- 
ing the PROCEDURE or ENTRY statement in 
which the parameter list occurs (though the 
same name may also appear in a DECLARE 
statement internal to the same block). 

The appearance of a statement label pre- 
fix constitutes explicit declaration of a 
statement label constant. 

The appearance of a name as the label of 
either a PROCEDURE or ENTRY statement is 
the same as if it were declared in a 
DECLARE statement immediately preceding the 
PROCEDURE statement for the procedure to 
which it refers. 
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SCOPE OF Mi EXPLICIT DECLARATION 

The scope of an explicit declaration of 
a name is that block to which the declara- 
tion is internal f but excluding all con- 
tained blocks to which another explicit 
declaration of the same identifier is 
internal . 



For example: 
PROCEDURE; 
DECLARE A r B; 
Q: PROCEDURE; 

DECLARE B f C; 

END 0; 
END P; 



] 



The lines to the right indicate the 
scope of the names. B and B* indicate the 
two distinct uses of the name B. 



CONTEXTUAL DECLARATION 

When a name appears in certain contexts, 
some of its attributes can be determined 
without explicit declaration. In such a 
case, if the appearance of a name does not 
lie within the scope of an explicit 
declaration for the same name, the name is 
said to be contextually declared. 

A name that has not been declared ex- 
plicitly will be recognized and declared 
contextually in the following cases: 

1. A name that appears in a CALL state- 
ment, in a CALL option, or followed by 
a parenthesized list in a function 

reference Cin a context where an 
expression is expected) is given the 
ENTRY and EXTERNAL attributes. 

2. A name that appears in a FILE option, 
or a name that appears in an ON, SIG- 
NAL, or REVERT statement for a condi- 
tion that requires a file name, is 
given the FILE and EXTERNAL 
attributes. 

3. A name that appears in an ON CONDI- 
TION, SIGNAL CONDITION, or REVERT CON- 
DITION statement is recognized as a 
user-defined condition name. 

*. A name that appears in an EVENT option 
or in a WAIT statement is given the 
EVENT attribute. 

5. A name that appears in a TASK option 
is given the TASK attribute. 



6. A name that appears in the BASED 

attribute, in a SET option, or on the 
left-hand side of a pointer qualifica- 
tion symbol is given the POINTER 
attribute. 



A name that appears in an IN option, 
or in the OFFSET attribute is given 
the AREA attriDute. Note, however, 
that all contextually declared area 
variables are given the AUTOMATIC 
attribute. The compiler requires that 
the variable named in the OFFSET 
attribute must be based; if a nonbased 
area variable is named f the offset 
variable will be changed to a pointer 
variable. Hence, unless the variable 
named in the OFFSET attribute is ex- 
plicitly declared, OFFSET effectively 
becomes POINTER, and a severe error 
occurs. 



8. If an undeclared identifier appears: 

a. before the equal sign in an as- 
signment statement, or 

b. before the assignment symbol in a 
DO statement Cor in a repetitive 
specification), or 

c. in the data list of a GET 

statement 

and if that identifier is neither en- 
closed within an argument list nor 
immediately followed by an argument 
list, that identifier is contextually 

declared to be a variable and not a 
reference to a built-in function or 
pseudo-variable. This rule does not 
apply to the identifiers ONCHAR, 
ONSOURCE, and PRIORITY. 

Examples of contextual declaration are: 

READ FILE CPREQ) INTO (Q) ; 

ON CONDITION CNEG) CALL CREDIT; 

In these statements, PREQ is given the FILE 
attribute, Kj£G is recognized as a user- 
defined condition name, and CREDIT is given 
the ENTRY attribute. The EXTERNAL attri- 
bute is given to all three by default « 



SCOPE OF A CONTEXTUAL DECLARATION 

The scope of a contextual declaration is 

determined as if the declaration were made 
in a DECLARE statement immediately follow- 
ing the PROCEDURE statement of the external 
procedure in which the name appears • 
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Note that contextual declaration has the 
same effect as if the name were declared in 
the external procedure, even when the 
statement that causes the contextual 
declarations is internal to a block (called 
B, for example) that is contained in the 
external procedure. Consequently, the name 
is known throughout the entire external 
procedure, except for any blocks in which 
the name is explicitly declared. It is as 
if block B has inherited the declaration 
from the containing external procedure. 

Since a contextual declaration cannot 
exist within the scope of an explicit 
declaration, it is impossible for the con- 
text of a name to add to the attributes 
established for that name in an explicit 
declaration. 



scope of an implicit declaration is deter- 
mined as if the name were declared in a 
DECLARE statement immediately following the 
first PROCEDURE statement of the external 
procedure in which the name is used. 

An implicit declaration causes default 
attributes to be applied, depending upon 
the first letter of the name. If the name 
begins with any of the letters I through N 
it is given the attributes REAL FIXED 
EINARY (15,0). If the name begins with any 
other letter including one of the alphabet- 
ic extenders $, #, or a, it is given the 
attributes REAL FLOAT DECIMAL (6). (The 
default precisions are those defined for 
System/360 implementations.) 



For example, the following procedure is 
invalid: 

P: PROC (F); 



READ FILE(F) INTO(X); 



EXAMPLES OF DECLARATIONS 

Scopes of data declarations are illus- 
trated in Figure 7. The brackets to the 
left indicate the block structure; the 
brackets to the right show the scope of 
each declaration of a name. In the dia- 
gram, the scopes of the two declarations of 
Q and R are shown as Q and Q* and R and R". 



END P; 

The identifier F is in a parameter list and 
is, therefore, explicitly declared. It is 
given the attributes REAL DECIMAL FLOAT by 
default. Since F is explicitly declared, 
its appearance in the FILE option does not 
constitute a contextual declaration. Such 
use of the identifier is in error. 



IMPLICIT DECLARATION 

If a name appears in a program and is 
not explicitly or contextually declared, it 
is said to be implicitly declared. The 



P is declared in the block A and known 
throughout A since it is not redeclared. 

Q is declared in A, and redeclared in B. 
The scope of the first declaration is all 
cf A except B; the scope of the second 
declaration is block B only. 

R is declared in block C, but a 
reference to R is also made in block B. 
The reference to R in block B results in an 
implicit declaration of R in A, the external 
procedure. Two separate names with dif- 
ferent scopes exist, therefore. The scope 
cf the explicitly declared R is C; the 
scope of the implicitly declared R is all 
°f A except block C. 



PROCEDURE; 
DECLARE P, Q; 
B: PROCEDURE; 
DECLARE Q; 
R = Q; 
C: BEGIN; 

DECLARE R; 
DO I = 1 TO 10; 
END; 
END C; 
END B; 
D: PROCEDURE; 
DECLARE S; 
END D; 
END A; 



Q f 



R' 



] 



Figure 7. Scopes of Data Declarations 
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I is referred to in block C. This 
results in an implicit declaration in the 
external procedure A. As a result, this 
declaration applies to all of A, including 

the contained procedures B f C and D. 



S is explicitly declared in procedure D 
and is known only within D. 

Scopes of entry name and statement label 
declarations are illustrated in Figure 8. 
The example shows two external procedures. 
The names of these procedures, A and E, are 
assumed to be explicitly declared with the 
EXTERNAL attribute within the procedures to 
which they apply. In addition, E is con- 
textually declared in A as an EXTERNAL 
<-nti~y name by its appearance in the CALL 
statement in block C. The contextual 
declaration of E applies throughout block A 
and is linked to the explicit declaration 
of E that applies throughout block E. The 
Lcope of the name E is all of block A and 
all of block E. The scope of the name A is 
only ail of the block A, and not E. in E, 
since the CALL statement itself would pro- 
vide a contextual declaration of A, which 
would then result in the scope of A being 
all of A and all of E. 

The label LI appears with statements 
internal to A and to C. Two separate 
declarations are therefore established; the 
first applies to all of block A except 
clock C, the second applies to block C 
only. Therefore, when the GO TO statement 
in block B is executed, control is trans- 
ferred to LI in block A, and block B is 
terminated. 

D and B are explicitly declared in block 
A and can be referred to anywhere within A; 
tut since they are INTERNAL, they cannot be 
referred to in block E (unless passed as an 

argument to E) . 



C is explicitly declared in B and can be 
referred to from within B, but not from 
outside B. 

L2 is declared in B and can be referred 
to in block B, including C, which is con- 
tained in B, but not from outside E. 



APPLICATION OF DEFAULT ATTRIBUTES 

The attributes associated with a name 
comprise those explicitly, contextually , or 
implicitly declared for that name, as well 
as those assumed by default. The default 
for each attribute is given in Part II, 
Section 9, "Attributes." 



THE INTERNAL AND EXTERNAL ATTRIBUTE S 

The scope of a name with the INTERNAL 
attribute is the same as the scope of its 
declaration. Any other explicit declara- 
tion of that name refers to a new object 
with a different, nonoverlapping scope. 

A name with the EXTERNAL attribute may 
be declared more than once in the same pro- 
gram, either in different external proce- 
dures or within blocks contained in exter- 
nal procedures. Each declaration of the 
name establishes a scope. These declara- 
tions are linked together and, within a 
program, all declarations of the same iden- 
tifier with the EXTERNAL attribute refer to 
the same name. The scope of the name is 
the sum of the scopes of all the declara- 
tions of that name within the program. 



Note: 



External names cannot be more than 



seven characters long for TSS/360 
implementation. 

Since these declarations all refer to 
the same thing, they must all result in the 



PROCEDURE; 

LI: P = Q; 

B: PROCEDURE; 

L2: CALL C; 

C: PROCEDURE; 
LI: X = Y; 
CALL E; 
END C; 

GO TO LI; 

END B; 
D: PROCEDURE; 

END D; 
CALL B; 
END A; 
PROCEDURE; 

END E; 



LI LI 1 L2 A B C E E 



Figure 8. Scopes of Entry and Label Declarations 
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same set of attributes. It may be imposs- 
ible for the compiler to check this, parti- 
cularly if the names are declared in dif- 
ferent procedures, so care should be taken 
to ensure that different declarations of 
the same name with the EXTERNAL attribute 
do have matching attributes. The attribute 
listing, which is available as optional 
output from the compiler, helps to check 
the use of names. The following example 
illustrates the above points in a program: 



A: PROCEDURE; 

DECLARE S CHARACTER (20); 
CALL SET (3) ; 
E: GET LIST (S,M,N) ; 
B: BEGIN; 

DECLARE X(M,N), Y Cfc) ; 
GET LIST (X,Y) ; 
CALL C(X,Y) ; 
C: PROCEDURE (P,Q) ; 

DECLARE P(*,*) , Q(*) , 

S BINARY FIXED EXTERNAL; 
S = 0; 

DO I = 1 TO M; 
IF SUM CPU,*)) = Q(I) 

THEN GO TO B; 
S = S+l; 

IF S = 3 THEN CALL OUT (E) ; 
CALL DCI> ; 
B: END; 

END C; 
D: PROCEDURE (N) ; 

PUT LIST ('ERROR IN ROW ', 

N, 'TABLE NAME ' , S) ; 
END D; 
END B; 
GO TO E; 
END A; 

OUT; PROCEDURE (R) ; 

DECLARE R LABEL, 

(M,L) STATIC INTERNAL 

INITIAL (0), 
S BINARY FIXED EXTERNAL, 
Z FIXED DECIMAL(l); 
M = M+l; S=0; 

IF M<L THEN STOP; EISE GO TO R; 
SET: ENTRY (Z>; 
L=Z; 
RETURN; 
END OUT; 

A is an external procedure name; its 
scope is all of block A, plus any other 
blocks where A is declared (explicitly or 
contextually) as external. 

S is explicitly declared in block A and 
block C. The character string declaration 
applies to all of block A except block C; 
the fixed binary declaration applies only 
within block C. Notice that although D is 
called from within block C, tb* reference 
to S in the PUT statement in D is to the 
character string S, and not to the S 
declared in block C. 



N appears as a parameter in block D, but 
is also used outside the block. Its 
apearance as a parameter establishes an 
explicit declaration of N within D; the 
references outside D cause an implicit 
declaration of N in block A. These two 
declarations of the name N refer to dif- 
ferent objects, although in this case, the 
objects have the same data attributes, 
which are, by default, FIXED (15,0), 
BINARY, and INTERNAL. 

X and Y are known throughout B and could 
fce referred to in block C or D within E, 
but not in that part of A outside B. 

P and Q are parameters, and therefore 
their appearance in the parameter list is 
sufficient to constitute an explicit 
declaration. However, a separate DECLARE 
statement is required in order to specify 
that P and Q are arrays. Note that 
although the arguments X and Y are declared 
as arrays and are known in block C, it is 
still necessary to declare P and Q in a 
DECLARE statement to establish that they, 
too, are arrays. (The asterisk notation 
indicates that the bounds of the parameters 
are the same as the bounds of the 
arguments. ) 

I and M are not explicitly declared in 
the external procedure A; they are there- 
fore implicitly declared and are kncwn 
throughout A, even though I appears only 
within block C. 

Within the external procedure A, OUT and 
SET are contextually declared as entry 
names, since they follow the keyword CALL. 
They are therefore considered to be 
declared in A and are given the EXTERNAL 
attribute by default. 

The second external procedure in the 
example has two entry names, SET and OUT. 
These are considered to be explicitly 
declared with the EXTERNAL attribute. The 
two entry names SET and OUT are therefore 
known throughout the two procedures. 



The label B 
gram, once as 
which is an ex 
label in A. I 
within block C 
fix to the END 
B in the GO TO 
therefore refe 
statement with 
any reference 
the begin blcc 



appears twice in the pro- 
the label of a begin block, 
plicit declaration, as a 
t is redeclared as a label 
by its appearance as a pre- 
statement. The reference to 
statement within block C 
rs to the label of the END 
in block C. Outside block C, 
to B would be to the label of 
:k. 



Note that C and D can be called from any 
point within B but not from that part of A 
outside B, nor from another external proce- 
dure. Similarly, since E is known through- 
cut the external procedure A, a transfer to 
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t may be nade from any point within A. The 
label B within block C, however, can only 
be referred to from within C. Transfers 
out of a block by a GO TO statement can be 
made; but such transfers into a nested 
block generally cannot. An exception is 
shown in the external procedure OUT, where 
the label E front block A is passed as an 
argument to the label parameter R. 



MULTIPLE DECLARATIONS AND AMBIGUO US 
REFERENCES 

Two or more declarations of the same 
identifier internal to the same block con- 
stitute a multiple declaration , unless at 
least one of the identifiers is declared 
within a structure in such a way that name 
qualification can be used to make the names 
unique. 



The statement GO TO R causes control 
pass to the Label E, even though E is 
dec' la red within 

(JUT < 



A, and not known within 



to Two or more declarations anywhere in a 

program of the same identifier as different 
names with the EXTERNAL attribute consti- 
tute a multiple declaration. 



The variables M and L are declared 
kithin the block OUT to be STATIC, so their 
vai its are preserved between calls to OUT. 

in order to identify the S in the proce- 
turt: OUT as the same S in the procedure C, 
ioth have been declared with the attribute 
bX TERN A I*. 



Multiple declarations are in error. 

A name need have only enough qualifica- 
tion to make the name unique. Reference to 
a name is always taken to apply to the 
identifier declared in the innermost block 
containing the reference. An ambiguous 
reference is a name with insufficient qual- 
ification to make the name unique. 



"l l 2^X^ of Me m ber Na mes of External 
:- : t -.rv.ct in es 

When a major structure name is declared 
wi*. ii the EXTERNAL attribute in more than 
one block, the attributes of the corre- 
sponding structure members must be the same 
in each case, although the corresponding 
member n ames need not be identical. Mem- 
be rs of structures always have the INTERNAL 
at'iibute, and cannot be declared with any 
scope attribute. However, a reference to a 
member of an external structure, using the 
member name known to the block containing 
the reference, is effectively a reference 
to tnat member in all blocks in which the 
external name is known, regardless of 
whether the corresponding member names are 
identical. For example: 

PROCA ; PROCEDURE ; 

DECLARE 1 A EXTERNAL, 
2 B, 
2 C; 



The following examples illustrate both 
irultipie declarations and ambiguous 
references; 



DECLARE 1 A, 
BEGIN; 
DECLARE 1 
A.C = D.E; 



2 C f 2 D, 3 E; 

A, 2 B, 3 C, 3 E; 



In this example, A.C refers to c in the 
inner block; D.E refers to E in the outer 
block. 

DECLARE 1A, 2 B, 2 B, 2 C, 3 D, 2 C; 

In this example, B has been multiply 
declared. A.D refers to the second D, 
since A.D is a complete qualif icaticn of 
cnly the second D; the first D would have 
to be referred to as A. CD. 

DECLARE 1A, 2B, 3 C, 2D, 3 C; 

In this example, A.C is ambiguous because 
neither C is completely qualified by this 
reference. 



END PROCA; 



DECLARE 1 A, 2 A, 3 A; 



PROCB: PROCEDURE; 

DECLARE 1 A EXTERNAL, 

2 B, 

2 D; 



END PROCB; 



In this example, A refers to the first A, 
A. A refers to the second A, and A. A. A 
refers to the third A. 



DECLARE X; 
DECLARE 1 Y, 



2 X, 3 Z, 3 A, 
2 Y r 3 Z, 3 A; 



In this example, if A.B is chanced in 
PROCA, it is also changed for PROCB, and 
vice versa; if A.C is changed in PROCA, A.D 
is changed for PROCB, and vice versa. 



In this example, X refers to the first 
DECLARE statement. A reference to Y.Z is 
ambiguous; Y.Y.Z refers to the second Z; 
and Y.X.Z refers to the first Z. 
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INPUT AND OUTPUT 



PL/I includes input and output state- 
ments that enable data to te transmitted 
between the internal and external storage 
devices of a computer. A collection of 
data external to a program is called a data 
set . Transmission of data from a data set 
to a program is termed input ,, and transmis- 
sion of data from a program to a data set 
is called output , 

PL/I input and output statements are 
concerned with the logical organization of 
a data set and not with its physical char- 
acteristics; a program can be designed 
without specific knowledge of the input/ 
output devices that will be used when the 
program is executed. To allow a source 
program to deal primarily with the logical 
aspects of data rather than with its phys- 
ical organization in a data set, PL/I em- 
ploys a symbolic representation of a data 
set called a file . A file can be asso- 
ciated with different data sets at dif- 
ferent times during the execution of a 
program. 

Two types of data transmission can be 
used by a PL/I program. In stream-oriented 
transmission , the organization of the data 
in the data set is ignored within the pro- 
gram, and the data is treated as though it 
actually were a continuous stream of indi- 
vidual data items in character form; data 
is converted from character form to inter- 
nal form on input, and from internal form 
to character form on output. In record- 
oriented transmission , the data set is con- 
sidered to be a collection of discrete rec- 
ords. No data conversion takes place dur- 
ing record transmission; on input the data 
is transmitted exactly as it is recorded in 
the data set, and on output it is trans- 
mitted exactly as it is recorded internal- 
ly. It is possible for the same data set 
to be processed at different times by eith- 
er stream transmission or record transmis- 
sion; however, all items in the data set 
would have to be in character form. 

Stream-oriented transmission is ideal 
for simple applications, particularly those 
that use terminal or punched card input and 
have limited output; a minimum of coding is 
required of the user, especially for ter- 
minal or punched card input and printed 
output. However, compared with record- 
oriented transmission, stream-oriented 
transmission is less efficient in terms of 
execution time because of the data conver- 
sion it involves, and more s^-.ce is 
required on external storage devices 
because all data is in character form. 



Although record-oriented transmission 
may demand rather more effort from the 
user, it is more versatile than stream- 
oriented transmission, with regard to the 
nanner in which data can be processed and 
the types of data set that can be pro- 
cessed. Since data is recorded in a data 
set exactly as it appears in main storage, 
any data format is acceptable; no conver- 
sion problems will arise, but the user must 
have a greater awareness of the structure 
of his data. 

This section discusses those aspects of 
PL/ I input and output that are common to 
stream-oriented and record-oriented trans- 
mission, including files and their attri- 
butes, and the relationship of files to 
data sets. Sections 9 and 10 describe the 
input and output statements that can be 
used in a PL/I program, and the various 
data set organizations that are recognized 
in PI/I. Stream-oriented transmission is 
dealt with in Part I, Section 9, and 
record-oriented transmission in Part I, 
Section 10. 



DATA SETS 

Data sets are stored on a variety of 
external storage media, such as punched 
cards, reels of magnetic tape, and disks. 
Despite their variety, these media have 
irany coiriron characteristics that permit 
standard methods of collecting, storing, 
and transmitting data. For convenience, 
the general term volume is used to refer to 
a unit of external storage, such as a reel 
of magnetic tape or a disk pack, without 
regard to its specific physical 
composition. 

The data items within a data set are 
arranged in distinct physical groupings 
called blocks . These blocks allow the data 
set to be transmitted and processed in por- 
tions rather than as a unit. For proces- 
sing purposes, each block may consist of 
cne or more logical subdivisions called 
records , each of which contains one or more 
data items. (Sometimes a block is called a 
physical record, because it is the unit of 
data that is physically transmitted to an 
its logical subdivisions are called logical 
record s. ) 

When a block contains two or more rec- 
ords, the records are said to be blocked . 
Elocked records often permit more compact 
and efficient use of storage. Consider how 
data is stored on magnetic tape; the data 
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between two successive interrecord gaps is 
one block, or physical record. If several 
logical records are contained within one 
block, the number of gaps is reduced, and 
much more data can be stored on a full 
length of tape, For example, on a tape of 
density 800 characters/inch with an inter- 
record gap of 0-6 inches, a card image of 
8 characters would take up 0.1 inches. If 
the records were unblocked, each record 
would require 0-1 inches, plus 0.6 inches 
for the interblock gap, making a total of 
0.7 inches. 100 records would therefore 
take up 70 inches of tape. If the records 
were blocked, however, at, say, 40 records 
to a block, each block of 10 records would 
take up 1 inch, plus 0.6 inches for the 
gap, making a total of 1 . 6 inches. Thus, 
100 records would now take up only 16 
inches of tape; this is less than 25 per- 
cent, of the amount needed for the unblocked 



Most data processing applications are 
concerned with logical records rather than 
hloc.Ks. Therefore, the input and output 
statements of PL/I generally refer to log- 
ical records; this allows the user to con- 
centrate on the data to be processed, 
without being directly concerned about its 
physical organization in external storage. 



FILES 

To allow a source 
inarily with the logi 
rather than with its 
in a data set, PL/I 
representation of a 
This symbolic repres 
input and output sta 
cess the associated 
data set, however, a 
cance only within th 
does not exist as a 
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ENVIRONMENT 



program 
cal a spec 

physical 
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data set 
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data set. 

file has 
e source 
physical 
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program and 
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PL/I requires a file name to be declared 
for a file, and allows the characteristics 
of the file to be described with keywords 
called file attributes , which are specified 
for the file name. The following lists 
show the attributes that are applicable for 
each type of data transmission: 



St ream- Oriented 

Tr ansmission 

FILE 

STREAM 

INPUT 

OUTPUT 

EXTERNAL 

INTERNAL 

PRINT 



Record-Oriented 

Transmission 

FILE 

RECORD 

INPUT 

OUTPUT 

UPDATE 

SEQUENTIAL 

DIRECT 



BUFFERED 

UNBUFFERED 

EXTERNAL 

INTERNAL 

BACKWARDS 

KEYED 

EXCLUSIVE 

ENVIRONMENT 



The TRANSIENT attribute is designed to 
allow teleprocessing applications programs 
to be written in PL/I. Since teleproces- 
sing is not supported in TSS/360, the TRAN- 
SIENT attribute is accepted by the compil- 
er, but the UNDEFINEDFILE condition is 
raised when an attempt is made to use a 
file with the TRANSIENT attribute. 

A detailed description of each of these 
attributes appears in Part II, Section 9, 
"Attributes." The discussions below give a 
brief description of each of the file 
description attributes and show how these 
attributes are declared for a file. The 
scope attributes, EXTERNAL and INTERNAL, 
are discussed in Part I, Section 7, "Recog- 
nition of Names." 



THE FILE ATTRIBUTE 

The FILE attribute indicates that the 
associated identifier is a file narre. For 
example, the identifier MASTER is declared 
to be a file name in the following 
statement : 



DECLARE MASTER FILE; 



The attributes as 
attribute fall into 
native attributes an 
An alternative attri 
chosen from a group 
explicit or implicit 
for one of the alter 
group and if one of 
required, a default 
although this is def 
when some attributes 
PL/I OPEN statement. 
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two categories: 
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bute is one that 
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An additive attribut e is one that must 
be stated explicitly or is implied by 
another explicitly stated attribute or 
name. The additive attribute KEYED can be 
implied by the DIRECT attribute. The addi- 
tive attribute PRINT can be implied by the 
standard output file name SYSPRINT. An 
additive attribute can never be applied by 
default. 

Note : With the exception of the INTERNAL 
and EXTERNAL scope attributes, all the 
alternative and additive attributes imply 

the FILE attribute. Therefore, the FILE 
attribute need not be specified for a file 
that has at least one of the alternative or 
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additive attributes already specified 
explicitly. The FILE attribute must be 
specified explicitly, however, if only the 
INTERNAL or EXTERNAL attribute is speci- 
fied; otherwise, the identifier will be 
assumed, by default, to be an arithmetic 
variable rather than a file name. 



ALTERNATIVE ATTRIBUTES 

PL/I provides five groups of alternative 
file attributes. Each group is discussed 
individually. Following is a list of the 
groups and the default for each: 



Group Alternative 
Type Attributes 
Usage STREAM | RECORD 



Default 
Attribute 

STREAM 



Function INPUT | OUTPUT | UPDATE INPUT 

I Access SEQUENTIAL | DIRECT SEQUENTIAL 

Buffering BUFFERED | UNBUFFERED BUFFERED 

Scope EXTERNAL | INTERNAL EXTERNAL 



The scope attributes are discussed in 
detail in Part II, Section 9, "Attributes"; 
a brief description of alternative attri- 
butes is given below. 

The STREAM and RECORD A ttributes 

The STREAM and RECORD attributes 
describe the type of data transmission 
(stream-oriented or record-oriented) to be 
used in input and output operations for the 
file. 

The STREAM attribute causes a file to be 
treated as a continuous stream of data 
items recorded only in character form. 

The RECORD attribute causes a file to be 
treated as a sequence of records, each 
record consisting of one or more data items 
recorded in any internal form. 

DECLARE MASTER FILE RECORD, 
DETAIL FILE STREAK; 

The INPUT, OUTPUT, and UPDATE Attributes 

The function attributes determine the 
direction of data transmission permitted 
for a file. The INPUT attribute applies to 
files that are to be read only. The OUTPUT 
attribute applies to files that are to be 
written only. The UPDATE attribute 
describes a file that is to be used for 
both input and output; it allows records to 
be inserted into an existing file and other 
records already in that file to be altered 
or deleted. 



DECLARE 

DETAII FILE INPUT, 
REPORT FILE OUTPUT, 
MASTER FILE UPDATE; 



The SEQ UENTIAL and DIRECT Attributes 

The access atritutes apply only to a 
file with the RECORD attribute, and provide 
information regarding access to the con- 
tents of the file. 



The SEQUENTIAL attribute specifies that 
successive records in the file are to be 
accessed on the basis of their successive 
physical positions, such as they are on 
magnetic tape. 



The DIRECT attribute sp 
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The BUFFERED and UNBUFFERED Attributes 

The buffering attributes apply only to 
files that have the SEQUENTIAL and RECORD 
attributes. The BUFFERED attribute indi- 
cates that records transmitted to and from 
a file must pass through an intermediate 
internal-storage area. Use of the BUFFERED 
attribute enables the system to automatic- 
ally overlap data transmission with other 
processing. The size of a buffer is usual- 
ly related to the size of the blocks (phys- 
ical records) in the data set associated 
with the file. 



The UNBUFFERED attribute indi 
a record in a data set need not 
through a buffer but may be tran 
directly to and from the interna 
associated with a variable. Any 
overlapping of data transmission 
processing is the responsibility 
user, who can use the EVENT opti 
purpose. The blocks and records 
ally the same size in a data set 
associated with an UNBUFFERED fi 
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Specification of UNBUFFERED does not 
preclude the use of buffers. In some 
cases, "hidden buffers" are required. 
These cases are listed in the discussion of 
the BUFFERED and UNBUFFERED attributes in 
Part II, Section 9, "Attributes." 
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ADDITIVE ATTRIBUTES 

The additive attributes are: 

PRINT 

BACKWARDS 

Ki-YED 

EXCLUSIVE 

ENVIRONMENT (option- list) 



Th- 



PRINT Attrj bote 



Tht- PRINT attribute applies only to 
files with the STREAM and OUTPUT attri- 
butes, It indicates that the file is 
eventually to be printed, that is, the data 
associated with the file is to appear on 
printed pages, although it may first be 
wti ct-t?n on some other medium. The PRINT 
act.ii.Liice causes the initial byte of each 
>. ecord of the associated data set to be 
iei>eivpd for a printer control character. 



1 i '1 f •: 



BACKWARDS Attribute 



The BACKWARDS attribute applies only to 
files with the SEQUENTIAL, RECORD, and 
InPUT attributes and only to data sets on 
magnetic tape. It indicates that a file is 
-co bt- accessed in reverse order, beginning 
v.irh tne last .record and proceeding through 
.he rile until the first, record is 
accessed . 

Tile _J< IXeP: Att ribute 

The KEYED attribute indicates that rec- 
oids in the file are to be accessed using 
one of the key options (KEY, KEYTO, or KEY- 
VROM) of data transmission statements or of 
the DELETE statement. Note that the KEYED 
Fit tribute does not necessarily indicate 
that the actual keys exist or are to be 
written in the data set; consequently, it 
need not be specified unless one of the key 
options is to be used. The STREAM attri- 
bute cannot be applied to a file that has 
!the KEYED attribute. The nature and use of 
keys is discussed in detail in Section 10, 
I "Record-Oriented Transmission." 

The EXCLU SIVE Attribute 

The EXCLUSIVE attribute applies only to 
files with the RECORD, DIRECT, and UPDATE 
attributes. Under TSS/360, the EXCLUSIVE 
attribute need not be declared, since 
re-eord-locking is automatic and cannot be 
suppressed by a NOLOCK option. 

The ENVIRONMENT Attribute 

The ENVIRONMENT attribute provides 
information that allows the compiler to 
determine the method of accessing the data 

(associated with a file. It specifies the 
physical organization of the data set that 



will be associated with the file, and indi- 
cates how the data set is to be handled. 

The general format of the ENVIRONMENT 
attribute is; 

ENVIRONMENT (option-list) 

The options appropriate to the two types of 
data transmission are described in the 
relevant sections in Part I, Section 9, 
"Stream-Oriented Transmission," and Section 
10, "Record-Oriented Transmission." 



OPENING AND CLOSING FILES 
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PL/I provides two statements, OPEN and 
CLOSE, to perform these functions. These 
statements, however, are optional. If an 
OPEN statement is not executed for a file, 
the file is opened automatically when the 
first data transmission statement for that 
file is executed; in this case, the auto- 
matic file preparation consists of standard 
system procedures that use information 
about the file as specified in a DECLARE 
statement (or assumed from a contextual 
declaration). Similarly, the file is 
closed automatically on termination of the 
program that opened it, if it has not been 
explicitly closed before termination. 

The OPEN Statement 

Execution of an OPEN statement causes 
one or more files to be opened explicitly. 
The OPEN statement has the following basic 
format : 

OPEN FILE (file-name) [option-list) 

( , FILE(f ile-name) Coption-list] ) . . . ; 

The option list of the OPEN statement can 
specify any of the alternative and additive 
attributes, except the INTERNAL, EXTERNAL, 
and ENVIRONMENT attributes. Attributes 
included as options in the OPEN statement 
are merged with those stated in a DECLARE 
statement. The same attributes need not be 
listed in both an OPEN statement and a 
DECLARE statement for the same file, and, 
cf course, there must be no conflict. 
Other options that can appear in the OPEN 
statement are the TITLE option, used to 
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associate the file name with the data set, 
and the PAGESIZE and LINESIZE options, used 
to specify the layout of a data set. The 
TITLE option is discussed below under 
"Associating Data Sets with Files," and the 
PAGESIZE and LINESIZE options, which apply 
only to STREAM files, in Part I, Section 9. 
The option list may precede the FILE (file 
name) specification. 

| For the TSS/360 PL/ I compiler, the OPEN 
statement is executed by library routines 
that are loaded dynamically at the time the 
OPEN statement is executed. Consequently, 
execution time can be reduced if more than 
one file is specified in the same OPEN 
statement. 

For a file to be opened explicitly, the 
OPEN statement must be executed before any 
of the input and output statements listed 
below in "Implicit Opening" are executed 
for the file. 



Merging of Attributes 

There must be no conflict between the 
attributes specified in a file declaration 
and the attributes merged, explicitly or 
implicitly, as the result of opening the 
file. For example, the attributes INPUT 
and UPDATE are in conflict, as are the 
attributes UPDATE and STREAM. 

After the attributes are merged, the 
attribute implications listed below are 
applied prior to the application of the 
default attributes discussed earlier. 
Implied attributes can also cause a con- 
flict. If a conflict in attributes exists 
after the application of default attri- 
butes, the UNDEFINEDFILE condition is 
raised. 

Following is a list of merged attributes 
and attributes that each implies after 
merging : 



Implicit Opening 

An implicit opening of a file occurs 
when one of the statements listed below is 
executed for a file for which an OPEN 
statement has not already been executed. 
The type of statement determines which 
unspecified alternatives are applied to the 
file when it is opened. 

The following list contains the state- 
ment identifiers and the attributes deduced 
from each: 

Statement Identifier Attributes Deduced 



GET 
PUT 
READ 

WRITE 

LOCATE 

REWRITE 

DELETE 

UNLOCK 



STREAM, INPUT 

STREAM, OUTPUT 

RECORD, INPUT 

(see Note) 



RECORD, OUTPUT 

(see Note) 

RECORD, OUTPUT 
SEQUENTIAL, BUFFERED 

RECORD, UPDATE 

RECORD, UPDATE 

RECORD, DIRECT, 

UPDATE, EXCLUSIVE 



Note : INPUT and OUTPUT are deduced from 
READ and WRITE only if UPDATE has uot been 
explicitly declared. 

An implicit opening caused by one of the 
above statements is equivalent o preceding 
the statement with an OPEN statement that 
specifies the deduced attributes. 



Merged Attributes 
UPDATE 

SEQUENTIAL 

DIRECT 

BUFFERED 

UNBUFFERED 

PRINT 

BACKWARDS 

KEYED 

EXCLUSIVE 



Implied Attributes 
RECORD 

RECORD 

RECORD, KEYED 

RECORD 

RECORD 

OUTPUT, STREAM 

RECORD, SEQUENTIAL 
INPUT 

RECORD 

RECORD, KEYED, 
DIRECT, UPDATE 



Note : The attributes SEQUENTIAL or DIRECT 
and BUFFERED or UNBUFFERED do not apply to 
a file with the STREAM attribute. 

The following two examples illustrate 
attribute merging for an explicit opening 
and fox an implicit opening. 

Explicit opening: 

DECLARE LISTING FILE STREAM; 



OPEN FILE (LISTING) PRINT; 

Attributes after merge due to execution of 
the OPEN statement are STREAM and PRINT. 
Attributes after implication are STREAM, 
PRING and OUTPUT. Attributes after default 
application are STREAM, PRINT, OUTPUT, and 
EXTERNAL . 
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Implicit opening: 

DECLARE MASTER FILE KEYED INTERNAL; 



READ FILE (MASTER) INTO 
(MASTER_RECORD) KEYTO (MASTER_J<EY) : 

Attributes after merge due to the opening 
caused by execution of the READ statement 
are KEYED, INTERNAL, RECORD, and INPUT. 
Attributes after implication are KEYED ff IN- 
TERNAL, RECORD r and INPUT (no additional 
attributes are implied) . Attributes after 
default application are KEYED, INTERNAL, 
RECORD, INPUT, SEQUENTIAL, and BUFFERED. 

Associating Data Sets With Files 

With TSS/360, the association of a file 
with a specific data set is accomplished 
using the TSS/360 command system, outside 
the PL/I program. At the time a file is 
opened, the PL/I file name is associated 
with the name Cddname) of a DDEF command, 
which is, in turn, associated with the name 
of a specific data set Cdsname) . Note that 
the direct association is with the name of 
a DDEF command, not with the name of the 
data set itself. 

A ddname can be associated with a PL/I 
file either through the file name or 
through the character-string value of the 
expression in the TITLE option of the asso- 
ciated OPEN statement. 

If a file is opened implicitly, or if no 

TITLE option is included in the OPEN state- 
ment that causes explicit opening of the 
file, the ddname is assumed to be the same 
as the file name. If the file name is 
longer than eight characters, the ddname is 
assumed to be composed of the first eight 
characters of the file name. 

Note : Since external names are limited to 
seven characters for the compiler, an ex- 
ternal file name of more than seven charac- 
ters is shortened into a concatenation of 
the first four and the last three charac- 
ters of the file name. Such a shortened 
name is not , however, the name used as the 
ddname in the associated DDEF command. 

Consider the following statements: 

1. OPEN FILE (MASTER) ; 

2. OPEW FILE(OLDMASTER) ; 

3. READ FILE (DETAIL). .. ; 

When statement number 1 is executed, the 
file name MASTER is taken to be t«.e same as 
the ddname of a DDEF command in the current 
task. When statement number 2 is executed, 



the name OLDMASTE is taken to be the same 
as the ddname of a DDEF command in the cur- 
rent task. IThe first eight characters of 
a file name form the ddname. Note, howev- 
er, that if OLBMASTER is an external name, 
it will be shortened by the compiler to 
OLDMTER for use within the program.) If 
statement number 3 causes implicit opening 
cf the file DETAIL, the name DETAIL is 
taken to be the same as the ddname of a 
DDEF command in the current task. 

I For RECORD I/O, in each of the above 
cases, a corresponding DDEF command must 
appear in the task; otherwise, the UNDE- 
FINEDFILE condition would be raised. The 

three DDEF commands would appear, in part, 

as follows: 

1 . DDEF DDNAME=MASTER , DSNAME= . . . 

2 . DDEF DDNAME=OLDMASTE, DSNAME= . . . 

3. DDEF DDNAME=DETAIL,DSNAME=.. . 

I For STREAM I/O, if no DDEF is given, the 
I records are read from/to SYSIN/SYSPRINT. 

If a file is opened explicitly by an 
OPEN statement that includes a TITLE 
option, the ddname is taken from the TITLE 
option, and the file name is not used out- 
side the program. The TITLE option appears 
in an OPEN statement as shown in the fol- 
lowing format: 

OPEN FILE (file- name) TITLE( expression) ; 

The expression in the TITLE option is eval- 
uated and converted to a character string, 
if necessary, that is assumed to be the 

ddname identifying the appropriate data 
set. If the character string is longer 
than eight characters, only the first eight 
characters are used. The following OPEN 

statement illustrates how the TITLE option 
might be used: 

OPEN FILE (DETAIL) TITLE ( f DETAILl 9 ) ; 

If this statement were executed for RECORD 
I/O, there must be a DDEF command in the 
current J ^sk with DETAILl as its ddname. 
It might appear, in part, as follows; 

DDEF DDNAKE=DETAIL1 ,DSNAME=DETAILA, . * , 

Thus, the data set DETAILA is associated 
with the file DETAIL through the ddname 
DETAILl. 

Although a data set name represents a 
specific collection of data, the file name 
can, at different times* represent entirely 
different data sets. Using the above 
example of the OPEN statement, whatever 
data set is named in the DSNAME parameter 
of the DETAILl DDEF command is the one that 
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is associated with DETAIL at the time it is 
opened. 

Use of the TITLE option allows a user to 
choose dynamically, at open time, one among 
several data sets to be associated with a 
particular file name. Consider the follow- 
ing example: 

DECLARE 1 INREC, 2 FIELD_1..., 

2 FILE_IDENT CHARACTER (8) , 
DETAIL FILE INPUT..., 
MASTER FILE INPUT...? 

OPEN FILE (DETAIL) ; 

READ FILE (DETAIL) INTO (INREC); 

OPEN FILE(MASTER) TITLE (FILE_IDENT) ; 

Assume that the program containing these 
statements is used to process several dif- 
ferent detail data sets, each of which has 
a different corresponding master data set. 
Assume, further, that the first record of 
each detail data set contains, as its last 
data item, a character string that identi- 
fies the appropriate master data set. The 
following DDEF commands might appear in the 
current task: 



is taken to be MASTER1A. After processing, 
the file is closed, dissociating the file 
name and the ddname. During the second 
iteration of the group, MASTER is opened 
again. This time, however, the value of 
the second element of IDENT is taken, and 
MASTER is associated with the ddname MAS- 
TER1B. Similarly, during the final itera- 
tion of the group, MASTER is associated 
with the ddname MASTER1C. 

Note: The TSS/360 command system does not 
allow the break character ( _ ) to appear 
in names. Consequently, this character 
cannot appear in ddnames. Care should thus 
fce taken to avoid using break characters 
among the first eight characters of file 
names, unless the file is to be opened with 
a TITLE option with a valid ddname as its 
expression. The alphabetic extender char- 
acters $, a, and #, however, are valid for 
ddnames, except in the first position. 

The CLOSE Statement 



The basic form of the CLOSE statement 



is: 



DDEF DDNAME=DETAIL, DSNAME=. . . 
DDEF DDNAME=MASTER1A,DSNAKE=MASTER1A 
DDEF DDNAME=MASTER1B , DSNAME=MASTER1B 
DDEF DDNAME=MASTER1C,DSNANE=MASTER1C 

In this case, MASTER1A, MASTER1B, and MAS- 
TER1C represent three different master 
files. The first record of DETAIL would 
contain as its last item, either 'MASTER- 
1A', 'MASTER1B', or ' MASTER1C", which is 
assigned to the character-string variable 
FILE__IDENT. When the OPEN statement is 
executed to open the file MASTER, the cur- 
rent value of FILE__IDENT would be taken to 
be the ddname, and the appropriate data set 
identified by that ddname would be asso- 
ciated with the file name MASTER. 

Another similar use of the TITLE option 
is illustrated in the following statements: 

DCL IDENTC3) CHAR(l) 

INITIAL ('A 1 , 'B', 'CM? 
DO I = 1 TO 3; 

OPEN FILE (MASTER) 

TITLE ( ' MASTER1 • | 1 IDENT ( I) ) ; 



CLOSE FILE(MASTER) ; 
END? 

In this example, IDENT is declare 1 as a 
character-string array with three elements 
having as values the specific character 
strings 'A 1 , 'B' , and ■C, When FASTER is 
opened during the first iteration of the 
DO-group, the character constant ' MASTER1* 
is concatenated with the value of the first 
element of IDENT, and the associated ddname 



CLOSE FILE (file-name) 

I r FILE (file-name)}...; 

Executing a CLOSE statement dissociates the 
specified file from the data set with which 
it became associated when the file was 
opened. The CLOSE statement also disso- 
ciates from the file all attributes estab- 
lished for it by the implicit or explicit 
opening process. If desired, new attri- 
butes may be specified for the file name in 
a subsequent OPEN statement. However, all 
attributes explicitly given to the file 
name in a DECLARE statement remain in 
effect. 

As with the OPEN statement, closing more 
than one file with a single CLOSE statement 
can save execution time. 

Note : Closing an already closed file or 
opening an already opened file has no 
effect. 



STANDARD FILES 

Two standard files are provided that can 
be used by any PL/ I program. One is the 
standard system file called SYSIN. The 
ether is the standard PL/I output file 
called SYSPRINT. On program execution, 
this PL/I file becomes the system file SYS- 
OUT. Standard files can be used only with 
stream-oriented transmission, and they 
differ from normal files in that their rec- 
ords cannot be reread or replaced. 

These files need not be declared or 
opened explicitly; they are opened automat- 
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ically, with a standard set of attributes. 
For SYSIN, these attributes specify that it 
is a stream-oriented input file. For SYS- 
PRINT f the standard attributes specify 
stream-oriented output- Both file names, 
SYSIN and SYSPRINT, are assumed to have the 
external attribute, even though SYSPRINT 
contains more than seven characters. 

These file names need not be explicitly 
stated in GET and PUT statements when these 
files are to be used. GET and PUT I/O 
statements that do not name any file, or 
that name a file which is not defined by a 
DDEF command in the current task, are equi- 
valent to: 

GET FILE (SYSIN). .. ; 
PUT FILE CSYSPRINT) 

It is more advantageous to name a file; 
this gives the user the option of substi- 
tuting for SYSIN or SYSPRINT at any time, 
by issuing a CDEF command for the file. 

Any references to SYSIN and SYSPRINT 
other than those in GET and PUT statements 
must be stated explicitly. 

The identifiers SYSIN and SYSPRINT are 
not reserved for the specific purposes 
described above. These identifiers can be 
used, except as external names, for other 



purposes besides identifying standard sys- 
tem files. Other attributes can be applied 
to them, either explicitly or contextually , 
but the PRINT attribute is applied automat- 
ically to SYSPRINT unless it is declared 
explicitly and without the STREAM OUTPUT 
attributes. 

Note : Special care must be taken when 
SYSIN or SYSPRINT is declared by the user 
as anything other than a STREAM file. The 
compiler causes, in effect, the identifier 
SYSIN to be inserted into each GET state- 
ment in which no file name is explicitly 
stated and the identifier SYSPRINT to be 
inserted into each PUT statement in which 
no file name is explicitly stated. Conse- 
quently, the following would be in error: 

DECLARE (SYSIN, SYSPRINT) FIXED 
DECIMAL (a, 2); 



GET LIST (A,B,C); 
PUT LIST (D,E,F); 

The identifier SYSIN would be inserted into 
the GET statement, and SYSPRINT in the PUT 
statement. In this case, however, they 
would not refer to the standard files, but 
to the fixed-point variables declared in 
the block. 
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SECTION 9: 



STREAM OFIEOTI^D TRANSMISSION 



This section describes the? input and 
output statements used in stream-oriented 
transmission, which is one of the two types 
of data transmission available in PL/I. 
Those features that apply equally to 
stream-oriented and record-oriented trans- 
mission, including files, file attributes, 
and opening and closing files, are 
described in Section 8, which forms a gen- 
eral introduction to this section and to 
Section 10. 

In stream-oriented transmission, a data 
set is treated as a continuous stream of 
data items in character form; within a pro- 
gram, block and record boundaries are 
ignored. However, a data set is considered 
to consist of a series of lines of data, 
and each data set that is created or 
accessed by stream-oriented transmission 
has a line size associated with it*. In 
general, a line is equivalent to a record 
in the data set; however, the line size 
does not necessarily equal, the record size. 

There are three modes of stream-oriented 
transmission: list-directed, data- 
directed, and edit-directed. The transmis- 
sion statements used in all three modes 
generally require the following information 



Input : In general, the data items in the 
stream are character strings in the form of 
optionally signed valid constants or in the 
form of expressions that represent complex 
constants. The variables to which the data 
is to be assigned are specified by a data 
list. Items are separated by a comma and/ 
or one or more blanks. 

Output : The data values to be transmitted 
are specified by a variable, a constant, or 
an expression that represents a data item. 
Each data item placed in the stream is a 
character-string representation that 
reflects the attributes of the variable. 
Items are separated by a blank. Leading 
zeros of arithmetic data are suppressed. 
Binary fixed-point and floating-point 
items, however, are character strings that 
express the value in decima 1 
representation. 

For PRINT files, data items are automat- 
ically aligned on implementation-defined 
preset tab positions. For the TSS/ J6G PL/ 1 
compiler, these positions are 1, 2 C >, U9, 
73, 97, and 121, but provision is n.nde for 
the user to alter these values (see PL / 1 
Programme r's G uide) . 



1. The name of the file associated with 
the data set from which data is to be 
obtained or to which data is to be 
assigned. 

2. A list of program variables to which 
data items are to be assigned during 
input or from which data items are to 
be obtained during output. This list 
is called a data list . On output, the 
data list can also include constants 
and other expressions. 

3. The format of each data item in the 
stream. 

Under certain conditions all of this 
required information can be implied; in 
other c«ases , only a portion of it need be 
stated explicitly. In list-directed and 
data-directed transmission, the formats of 
data items are not specified in the state- 
ments. And in data-directed transmission, 
even the data list is optional. 



LIST-DIRECTED TRANSMISSION 

List-directed transmission permits the 
user to specify the variables to which data 
is assigned and to specify data to be 
transmitted without specifying the format. 



DATA- DIRECTED TRANSMISSION 

Data-directed transmission permits the 
user to transmit self -identifying data. 

Input : Each data item in the stream is, in 
the form ot an assignment statement that 
specifies both the value and the varianle 
to which it is to be assigned. In general, 
values are in the form of constants. Items 
are separated by a comma and/or one or more 
blanks. A semicolon must end each group ot 
items to be accessed by a single GET state- 
ment. A data list in the GET statement is 
optional, since the semicolon determines 
the number of items to be obtained from the 
stream. 

Output : The data values to be transmitted 
may be specified by an optional data list. 
Each data item placed in the stream has the 
form of an assignment statement without a 
semicolon. Items are separated by a blank. 
The last item transmitted by each PUT 
statement is followed by a semicolon. 
Leading zeros of arithmetic data are sup- 
pressed. The character representation of 
each value reflects the attributes of the 
variable, except for fixed -point and 
floating-point binary items, which appear 
as values expressed in decimal notation. 
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If the data list is omitted, it is 

assumed to specify all variables that are 
known within the block containing the 

statement and are permitted in data- 
directed output. 

For PRINT files, data items are automat- 
ically aligned on the implementation™ 
defined preset tab positions referred to 
under "List-Directed Transmission." 



EDIT- DIRECTED TRANSMISSION 

Edit-directed transmission permits the 
user to specify the variables to which data 
is to be assigned or to specify data to be 
transmitted, and to specify the format for 
each item on the external medium. 

Input : Data in the stream is a continuous 
string of characters? different data items 

are not separated. The variables to which 
the data is to be assigned are specified by 
a data list. Format items in a format list 

specify the number of characters to be 
assigned to each variable and describe 
characteristics of the data (for example,' 
the assumed location of a decimal point) . 

Output ; The data values to be transmitted 
are defined by a data list* The format 

that the data is to have in the stream is 

defined by a format list. 



DATA TRANSMISSION STATEMENTS 

Stream-oriented transmission uses only 
one input statement f GET, and one output 
statement, PUT. A GET statement gets the 
next series of data items from the stream, 
and a PUT statement puts a specified set of 
data items into the stream. The variables 
to which data items are assigned, and the 
variables or expressions from which they 
are transmitted, are generally specified in 
a data list with each GET or PUT statement. 
The statements may also include options 
that specify the origin or destination of 
the data or indicate where it appears in 
the stream relative to the preceding data. 

The following is a summary of the 
stream-oriented data transmission state- 
ments and their options: 

STREAM INPUT : 

GET{ [FILE (filename) ) [data-specification! 
(COPY] (SKIPC (expression) J) >I 
(STRING (character-string-name) 
data-specification} ; 

STREAM OUTPUT : 

PUT{ [FILE (filename) J (data-specif icationl 
[SKIP! (expression) J ) 1| 



f STRING (character- st ring- name) 
data-specif i cation) ; 

STREAM OUTPUT PRINT : 

PUT (FILE (tile-name)J 

[data-specification] 
'PAGE (LINECexpression>f| 
SKIP ( (expression) 1 
..LINE (expression) J 

The options may appear in any order. The 
data specification can have one of the fol- 
lowing forms: 

LIST (data-list) 

DATA ((data-list)] 

EDIT Cdata-list) (format-list) 

[ (data-list) (format-list) J . . . 

The data specification can be omitted for 
STREAM OUTPUT PRINT files only if one of 
the control options (PAGE, SKIP, or LINE) 
appears. Format lists may use any of the 
following format items: 



A,B,C,E,F, 
P,R,X, 
SKIP ((w)] 
COLUMN (w) 

PAGE 
LINE (w) 



which may be used with 
any STREAM file 



which can be used with 
STREAM OUTPUT PRINT 
files only 



A, B,C, E, F,P,R, X which may be used with 

the STRING option 

The statements are discussed individually 
in detail in Part II, Section 10, 
"Statements." 



OPTIONS OF TRANSMISSION STATEMENTS 



The FILE and STRING Options 



The FILE option speci 
the file npon which the 
take place. The STRING 
and PUT statements to be 
data between internal st 
rather than between inte 
storage. If neither the 
the STRING option appear 
ment, the standard input 
assumed? if neither opt i 
statement, the standard 
PRINT is assumed. 



fies the name of 
operation is to 
option allows GET 

used to transmit 
orage locations 
rnal and external 

FILE option nor 
s in a GET state-. 

file SYSIN is 
on appears in a PUT 
output file SYS- 



Examples of the use of the FILE option 
are given in some of the statements below; 
Part I, Section 11, "Editing and String 
Handling," illustrates the use of the 
STRING option. 
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The COPY Option 

The COPY option should appear only in a 
GET FILE statement. It specifies that each 
data item is to be written, exactly as 
read, into the standard output file SYS- 
PRINT- For example, the statement 

GET FILE(SYSIN) DATA (A, B,C) COPY; 

not only transmits the values assigned to 
A, B, and C in the input stream to the 
variables with these names, but also causes 
them to be printed out in data-directed 
format. 

T he SKIP Option 

The SKIP option specifies a new current 
line Cor record) within the data set* The 
parenthesized expression is converted to an 
integer w f which must be greater than zero 
(unless the file is a PRINT file)* The 
data set is positioned to the start of the 
wth line (record) relative to the current 
line (record) . 

For non-PRINT files, if the expression 
is omitted or if w is not greater than 
zero, a value of 1 is assumed. For PRINT 
files, it w is less than or equal to zero, 
the effect is that of a carriage return 
with the same current line. 



the data specification- If both the PAGE 
option and the LINE option appear in the 
same statement, the PAGE option is applied 
first. For example, the statement 

PUT FILE (LIST) DATA(P,Q,R) 
LINE (34) PAGE; 

causes the values of the variables P, Q, 
and R to be printed in data-directed format 
on a new page, commencinq at line 34. 



DATA SPECIFICATIONS 

Data specifications are given in GET and 
PUT statements to identify the data to be 
transmitted. The data specifications 
correspond to the modes of transmission. 

Data Lists 

List-directed, data-directed, and edit- 
direct ed data specifications require a data 
list to specify the data items to be 
transmitted. 

General format: 

(data-list) 

where "data list" is defined as: 
element [ , element] . . . 



The SKIP option takes effect before the 
transmission of any values defined by the 
data specification, even if it appears 
after the data specification. Thus, the 
statement 

PUT LIST(X,Y,Z) SKIP (3); 

causes the values of the variables X, Y, 
and Z to be printed on the standard output 
file SYSPRINT commencing on the third line 
after the current line. 

The PAGE Option 

The PAGE option can be specified only 
for PRINT files. It causes a new current 
page to be defined within the data set. 
The PAGE option takes effect before the 
transmission of any values defined by the 
data specification (if any), even if it 
appears after the data specification. 

The LINE Option 

The LINE option can be specified only 
for PRINT files. It causes blank lines to 
be inserted so that the next line will be 
the wth line of the current page, where w 
is the value of the parenthesized expres- 
sion when converted to an integer. The 
LINE option takes effect before the trans- 
mission of any values defined by the data 
specification (if any) , even if it follows 



Syntax rules: 

The nature of the elements depends upon 
whether the data list is used for input or 
for output. The rules are as follows: 

1. On input , a data- list element for 

edit-directed and list-directed trans- 
mission can be one of the following: 
an element, array, or structure vari- 
able, a pseudo- variable, or a repeti- 
tive specification (similar to a 
repetitive specification of a DO 
group) involving any of these ele- 
ments. For a data-directed data spe- 
cification, a data-list element can be 
an element, array, or structure vari- 
able. None of the names in a data- 
directed data list can be subscripted, 
but qualified names are allowed. 

2 - ° n output , a data-list element for 
edit-directed and list-directed data 
specifications can be one of the fol- 
lowing: an element expression, an 
array expression, a structure expres- 
sion, or a repetitive specification 
involving any of these elements. For 
a data-directed data specification, a 
data- list element can be an element, 
array, or structure variable, or a 
repetitive specification involving any 
of these elements. Subscripts are 
allowed for data- directed output. 
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3. The elements of a data list must be of 

arithmetic or string data ty pe- 
ll. A data list must always be enclosed in 
parentheses. 

REPETITIVE SPECIFICATION : The general for- 
mat of a repetitive specification is shown 
in Figure 9. 

Syntax rules : 

1. An element in the element list of the 
repetitive specification can be any of 
those allowed as data-list elements as 
listed above, 

2. The expressions in the specification, 

which are the same as those in a DO 
statement, are described as follows: 

a. Each expression in the specifica- 
tion is an element expression. 

b. In the specification, expression- 1 
represents the starting value of 
the control variable or pseudo- 
variable* Expression-3 represents 
the increment to be added to the 
control variable after each repe- 
tition of data-list elements in 

the repetitive specification. 
Express ion- 2 represents the ter- 
minating value of the control 
variable* Expression- 4 represents 
a second condition to control the 
number of repetitions* The exact 
meaning of the specification is 
identical to that of a DO state- 
ment with the same specification. 
When the last specification is 
completed # control passes to the 
next element in the data list. 

3. Each repetitive specification must be 
enclosed in parentheses , as shown in 
the general format* Note that if a 
repetitive specification is the only 
element in a data list, two sets of 
outer parentheses are required, since 
the data list must have one set of 
parentheses and the repetitive speci- 
fication must have a separate set. 



4. As Figure 9 shows, the "specif i cation* 
portion of a repetitive specification 
can be repeated a number of times, as 

in the following form: 



DO I = 1 TO H, 6 TO 10 



Repetitive specifications can be 
nested? that is, an element of a 
repetitive specification can itself be 
a repetitive specification. Each DO 
portion must be delimited on the right 
with a right parenthesis (with its 
matching left parenthesis added to the 
beginning of the entire repetitive 
specification) . 

When DO portions are nested, the 
rightmost DO is at the outer level of 
nesting. For example, consider the 
following statement: 

GET LIST CC(AC1,J) DO I = 1 TO 2) 
DO J = 3 TO li)); 

Note the three sets of parentheses, in 
addition to the set used to delimit 
the subscript. The outermost set is 
the set required by the data list; the 
next is that required by the outer 
repetitive specification. The third 
set of parentheses is that required by 
the inner repetitive specification. 
This statement is equivalent to the 
following nested DO-groups: 

DO J = 3 TO 4 ; 

DO I = 1 TO 2; 

GET LIST CA CI, J)) j 

END; 
END; 

It gives values to the elements of the 
array A in the following order: 

AM, 3), A(2,3) f A(l,4), A(2 f «0 



Note : Although the DO keyword is used in 

the repetitive specification, a correspond- 
ing END statement is not allowed. 



(element E , element] . 



expression-1 



.DO 



»lej 



variable 
[ pseudo-variah. 

A •specification" has the following format: 

^TO expression- 2 EBY expression-3 
BY expression-3 [TO expression-2 



specif icationE, specification] . . . ) 



3 



[WHILE (expression- 4) ] 



Figure 9. General Format for Repetitive Specifications 
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TRANSMISSION OF DATA-LIST ELEMENTS : If a 
data-list element is of complex mode, the 
real part is transmitted before the 
imaginary part. 

If a data-list element is an array vari- 
able, the elements of the array are trans- 
mitted in row-major order, that is, with 
the rightmost subscript of the array vary- 
ing most frequently. 

±±. ct uc*ta-Ai&t element is a structure 
vdiiabie, the elements of the structure are 
transmitted in the order specified in the 
structure declaration. 

For example, if a declaration is: 

DECLARE 1 A (10), 2 B, 2 C; 

then the statement : 

PUT FILE(X) LIST(A); 

would result in the output being ordered as 
follows: 

A.B<1> A.C(l) A.B(2> A.CC2) A.BC3) 
A.CC3) . . .etc. 

If, however, the declaration had been: 

DECLARE 1 A, 2 B(10), 2 CC10); 

then the same PUT statement would result in 
the output being ordered as follows: 

A.B(l) A.BC2) A.B(3) ...A.B(IO) 
A.CC1) A.CC2) A.C(3> . ..A.C(IO) 

If, within a data list used in an input 
statement for list-directed or edit- 
directed transmission, a variable is 
assigned a value, this new value is used if 
the variable appears in a later reference 
in the data list. Example: 

GET LIST (N,(X(I) DOI=l TO (), J, K, 
SUBSTR (NAME, J,K)); 

When this statement is executed, data is 
transmitted and assigned in this order: 

1. A new value is assigned to N. 

2. Elements are assigned to the array X 
as specified in the repetitive speci- 
fication in the order X(l), X<2),. ..X 
(N) , with the new value of N used to 
specify the number of items to be 
assigned. 

3. A new value is assigned to J. 

** . A new value is assigned to K. 

5. A substring of length K is assigned to 
the string variable NAME, beginning at 
the Jth character. 



LIST-DIRECTED DATA SPECIFICATION 

The general format of a list- directed 
data specification, either input or output, 
is: 

LIST (data-list) 

The data list is described under =Data 
Lists," above. The keyword LIST must 
appear to specify the list-directed mode of 
transmission . 

List-Directed Data in the Stream 

Data in the stream, either input or out- 
put, is of character data type and has one 
of the following general forms: 

{♦)-] arithmetic-constant 

character-string-constant 

bit-strinq-constant 

{♦ |-] real-constant {+( - ) imaginary-constant 

These forms correspond exactly to the forms 
used for writing optionally signed con- 
stants in a PL/I program. However, ster- 
ling constants cannot be used A string con- 
stant must be one of the two permitted 
forms listed above; iteration and string 
repetition factors are not allowed. A 
blank must not precede the central ♦ or - 
in complex expressions. 

List-Directed Input Format 

When the data named is an array, the 
data consists of constants, the first of 
which is cALisrgned to the first element of 
the array, the second constant to the 
second element, etc., in row-ma ior order. 

A structure name in the data list r^prr*- 
sents a list of the contained element 
variables and arrays in the order specified 
in the structure description. 

On input, each pair of data items in the 
stream must be separated either by a blank, 
a comma, or a carriage return. This 
separator may be surrounded by an arbitrary 
number of blanks. A null field in the 
stream is indicated either by the first 
non-blank character beinq a comma, or by 
two commas separated by an arbitrary number 
of blanks. A null field specifies that the 
value of the associated item in the data 
list is to remain unchanged. 

The transmission of the list of con- 
stants on input is terminated by expiration 
of the list or by the end-of-file condi- 
tion. In the former case, positioning in 
the stream for the next GET statement is 
always at the character following the first 
blank or comma following the last data item 



Section 9: Stream-Oriented Transmission 8 3 



Page of C5C28-20U5-1 , Issued September 30, 1971 by TNL GN28-3185 



transmitted. More than one blank can 
separate two data items, and a comma 
separator may be preceded or followed by 
one or more blanks. In such cases, a sub- 
sequent GET statement will ignore interven- 
ing blanks and the comma Cif present) and 
will access the next data item. However, 
if an edit-directed GET statement should 
follow, the first character accessed will 
be the character to which the file has been 
positioned Cin other words, the next data 
item will begin with the first character 
following the blank or comma that separated 
it from the previous data item). 



Character strings are written out. If 
the file does not have the attribute PRINT, 
enclosing apostrophes are supplied, and 
contained apostrophes are replaced by two 
apostrophes. The field width is the cur- 
rent length of the string plus the number 
of added a|)ostrophes. If the file has the 
attribute PRINT, enclosing apostrophes are 
not supplied, and contained apostrophes are 
unmodified. The field width is the current 
length of the string. 

Examples of list- directed data 
specifications: 



If the data is a character-string con- 
stant, the surrounding apostrophes are 
removed, and the enclosed characters are 
interpreted as a character string. 



LIST (CARD, RATE, DYNAMIC^FLOW) 

LIST C (THICKNESS (DISTANCE) 
DO DISTANCE = 1 TO 1000)) 



If the data is a bit-string constant, 
enclosing apostrophes and the trailing 
character B are removed, and the enclosed 

charac ers are interpreted as a bit string. 

If the data is an arithmetic constant or 
complex expression, it is converted to 
coded arithmetic form with the base, scale, 
mode, and precision implied by the 
constant . 



LIST (P, Z, M # R) 

LIST (A*B/C, (X+Y)**2> 

The specification In the last example 
can be used only tor output, since it con- 
tains operational expressions. Such ex- 
pressions are evaluated when the statement 
is executed, and the result is placed in 
the stream. 



Data type conversions follow the rules 
for conversion from character type, as 
listed in Part II, Section 6, "Problem Data 
Conversion. " 

List-Directed Output Format 



DATA-DIRECTED DATA SPECIFICATION 

The general format o£ a data-directed 
data specification, for either input or 
output, is: 



The values of the element variables and 
expressions in the data list are converted 
to character representations and transmit- 
ted to the data stream. 

A blank separates successive data items 
transmitted. (For PRINT files, items are 
separated according to program tab 
settings. ) 



The length of th 
the stream is a fun 
of the data item, i 
length. Detailed d 
version rules and t 
sion are listed in 
conversion to chara 
Section 6, "Problem 



e data field placed in 
ction of the attributes 
ncluding precision and 
iscussions of the con- 
heir effect upon preci- 
the sections covering 
cter type in Part II, 
Data Conversion." 



Fixed-point and floating-point binary 
data items are converted to decimal nota- 
tion before being placed in the stream. 

For numeric character values, the 
character-string value is transmitted. 

Bit strings are converted to character 
representation of bit-string constants, 
consisting of the characters and 1, en- 
closed in apostrophes, and followed by the 
letter B. 



DATA [(data-list) } 

General rules: 



1. 



The data list is described in "Data 
Lists" in this section. It cannot 
include parameters, defined variables, 
or based variables. For input, the 
data list cannot contain subscripted 
names. Names of structure elements in 
the data list need only have enough 
qualification to resolve any ambigui- 
ty; full qualification is not 
required. On input, if the stream 
contains a name that does not have a 
counterpart in the data list, the NAME 
condition in raised. 

Omission of the data list implies that 
a data list is assumed. This assumed 
data list contains all the names that 
are known to the block and are valid 
for data-directed transmission. o n 
input, if the stream contains a name 
not known within the block, the NAME 
condition is raised. If the assumed 
data list contains a name that is not 
included in the stream, the value of 
the associated variable remains 
unchanged. On output, all items in 
the assumed data list are transmitted. 
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When a name occurs in more than one 
block, all data with that name in the 
active blocks is transmitted, not only 
data with that name within the scope 
of the current block. 

3. On input, recognition of a semicolon 
or an end of file in the stream causes 
transmission to cease, whether or not 
a data list is specified. On output, 
a semicolon is written into the stream 
after the last data item transmitted 
by each PUT statement. 

Data- Directed Data in the Stream 

The data in the stream associated with a 
data-directed transmission statement is in 
the form of a list of element assignments 
having the following general format (the 
optionally signed constants, like the vari- 
able names and the equal signs, are in 
character form) : 

element-variable = constant 
I ( {b| , | cr) element-variable = constant)...; 

General rules: 

1. The element variable may be a sub- 
scripted name. Subscripts must be 
optionally signed decimal integer 
constants. 

2. On input, the element assignments may 
be separated by either a blank (b in 

I the above format) f a comma, or a car- 
riage return (cr in the above format) . 
Redundant blanks are ignored. On out- 
put, the assignments are separated by 
a blank. 

3. Each constant in the stream has one of 
the forms described for list-directed 
transmission. 

Data-Directed Input Format 

General rules for data-directed input : 

1. If the data specification does not 
include a data list, the names in the 
stream may be any names known at the 
point of transmission. Qualified 
names in the input stream must be 
fully qualified. 

2. If a data list is used, each element 
of the data list must be an element, 
array, or structure variable. Names 
cannot be subscripted, but qualified 
names are allowed in the data list. 
All names in the stream should appear 
in the data list; however, the order 
of the names need not be the same, and 
the data list may include names that 
do not appear in the stream. 

For example, consider the following 
data list, where A, B, C, and D are 
names of element variables: 



DATA (B, A, C, D) 

This data list may be associated with 
the following input data stream: 

A=2.5, B=. 00*47, D=12S, Z=*ABC'; 

Note: C appears in the data list but 
not in the stream? its value remains 
unaltered. Z, which is not in the 
data list, raises the NAME condition. 

If the data list includes the name of 
an array, subscripted references to 
that array may appear in the stream 
although subscripted names cannot 
appear in the data list. The entire 
array need not appear in the stream,- 
only those elements that actually 
appear in the stream will be assigned. 

Let X be the name of a two-dimensional 
array declared as follows: 

DECLARE X (2,3)FIXED (6,2); 

Consider the following data list and 
input data stream: 

Data List Input Data Stream 
DATA (X) X(1,1)=7.9S, X(1,2)=808S, 
X(l, 3)=73; 

Although the data list has only t he- 
name of the array, the associated 
input stream may contain values for 
individual elements of the? array. In 
this case, only three elements are 
assigned; the remainder of the array 
is unchanged. 

If the data list includes the names of 
structure elements, then fully quali- 
fied names must appear in the stream, 
although full qualification is not 
required in the data list. Consider 
the following structures: 

DECLARE 1 CARDIN, 2 PARTNO, 2 DECCRP, 

2 PRICE, 3 RETAIL, 3 WHSL, 

1 CARDOUT, 2 PARTNO, 2 DESCRP, 

2 PRICE, 3 RETAIL, 3 WHSL; 

If it is desired to read a value for 
CARDIN. PRICE. RETAIL, the data specifi- 
cation and input data stream could 
have the following forms: 

Data Specification 
DATA (CARDIN. RETAIL) 

Input Data Stream 

CARDIN. PRICE. RETAIL = 4.28; 

Interleaved subscripts cannot appear 
in qualified names in the stream. All 
subscripts must be moved all the way 
to the right, following the last name 
of the qualified name. For example, 
assume that Y is declared as follows: 
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DECLARE 1 Y(S,5),2 A(10>, 3 B f 

3 C, 3 D; 

An element name would have to appear 
in the stream as follows: 

Y.A.B(2,3,8> = 8.72 

The name in the data list could not 
contain the subscript. 

Data- Directed Output Format 

General rules for data-directed output : 

1. An element of the data list may be an 
element, array, or structure variable, 
or a repetitive specification involv- 
ing any of these elements or further 
repetitive specifications. Sub- 
scripted names can appear. The names 
appearing in the data list, together 
with their values, are transmitted in 
the form of a list of element assign- 
ments separated by blanks and ter- 
minated by a semicolon. (For PRINT 
files, items are separated according 
to program tab settings.) 

2. Array variables in the data list are 
treated as a list of the contained 
subscripted elements in row-major 
order. 

Consider an array declared as follows: 

DECLARE X (2, 4> FIXED; 

If X appears in a data list as follows: 

DATA (X) 

on output, the output data .stream 
would have the form: 

X(l,l)=l X(l,2)=2 X(l,3>=3 
X(l f 4>=4 XC2,1)=5 XC2i2)=6 
X(2, 3) =7 XC2,4)=8; 

Note: In actual output, more than one 
blank would follow the equal sign. In 
conversion from coded arithmetic to 
character, leading zeros are converted 
to blanks, and up to three additional 
blanks may appear at the beginning of 
the field. 

3. Subscript expressions that appear in a 
data list are evaluated and replaced 
by the value. 

4. Items that are part of a structure 
appearing in the data list are trans- 
mitted with the full qualification, 
but subscripts follow the qualified 
names rather than being interleaved. 
If a data list is specified for a 
structure element transmitted under 
data-directed output as follows: 

DATA (Y(1,-3).Q> 



the associated data field in the out- 
put stream is of the form; 

Y.g(l,-3)= 3.756? 

5. The number of characters in a quali- 
fied name must not exceed 256. 

6. Structure names in the data list are 
interpreted as a list of the contained 
element or elements, and any contained 
arrays are treated as above. 

Consider the following structure: 

DECLARE 1 A, 2 B, 2 C, 3 D; 

If a data list for data-directed out- 
put is as follows: 

DATA (A) 

and the values of B and D are 2 and 
17, respectively, the associated data 
fields in the output stream would be: 

A.B= 2 A.C.D= 17; 

7. In the tollowiiig cases, data-directed 
output is not valid tor subsequent 
data-directed input: 

a. When the precision attribute of a 
fixed- ^Xiint variable is such that 
the assumed point is located out- 
side the field with assumed zeros 
intervening; that is, it for preci- 
sion Cp,q) p is less than q, or g 
is less than zero. (In this cas*» 
an exponent is transmitted, pre- 
ceded by a Letter F which is not: 
valid tor conversion to arithmetic 
type. ) 

b. When the character-string value of 
a numeric character variable does 
not represent a valid optionally 
signed arithmetic constant. For 
example, this is always true for 
complex numeric character variables. 

Length of Data-Directed Output Fields 

The length of the data field on the 
external medium is a function of the attri- 
butes declared for the variable and, since 
the name is also included, the length of 
the fully qualified subscripted name. The 
field length or output items converted from 
Coded arithmetic data, numeric character 
data, and bit-string data is the same as 
that for list-directed output data, and is 
governed by the rules for data conversion 
to character type as described in Part II, 
Section 6, "Problem Data Conversion." 

For character-string data, the contents 
of the character string are written out en- 
closed in apostrophes. Each apostrophe 
contained within the character string is 
represented by two successive apostrophes. 
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In the example shown in Figure 10 , A is 
declared as a one- dimensional array of six 
elements; B is a one-dimensional array of 
seven elements. The procedure calculates 
and writes out values for All) = B(I*1) ♦ 
BCD. 



EDIT-DIRECTED DATA SPECIFICATION 

General format for an edit-directed data 
specification, either for input or output, 
is as follows: 

EDIT (data-list) (format- list) 

[ (data-list) (format-list) ] . . . 



| Syntax rules: 



The data list, which must be enclosed 
in parentheses, is described above in 
"Data Lists." The format list, which 
also must be enclosed in parentheses, 
contains one or more format items. 
There are three types of format items: 
data format items, which describe data 
in the stream; control format items, 
which describe page, line, and spacing 
operations; and remote format items, 
which specify the label of a separate 
statement that contains the format 
list to be used. Format lists and 
format items are discussed in more 
detail in "Format Lists, ■ below. 
Edit-directed transmission is the only 
mode that can be used for reading or 
writing sterling data, by use of a 
picture specification. 

For nonconversational input, data in 
the stream is considered to be a con- 
tinuous string of characters not 
separated into individual data items. 
The number of characters for each data 
item is specified by a format item in 
the format list. The characters are 
treated according to the associated 
format item. 

For conversational input, the preced- 
ing rule applies, except that a car- 



riage return delimits an incompletely 
entered item: 



• If the target item is a varying 
string, the input is transmitted as 
is; no extra blanks are inserted. 



• If the target item is not a varying 
string, the input is padded on the 
right with blanks to give it the 
necessary field width. 

4. For output, the value of each item in 
the data list is converted to a format 
specified by the associated format 
item and placed in the stream in a 
field whose width also is specified by 
the format item. 

5. For either input or output, the first 
data format item is associated with 
the first item in the data list, the 
second data format item with the 
second item in the data list, and so 
forth. If a format list contains 
fewer format items than there are 
items in the associated data list, the 
format list is reused; if there are 
excessive format items, they are 
ignored. Suppose a format list con- 
taining five data format items and its 
associated data list specifies ten 
items to be transmitted. Then the 
sixth item in the data list will be 
associated with the first data format 
item, and so forth. Suppose a format 
list contains ten data format items 
and its associated data list specifies 
only five items. Then the sixth 
through the tenth format items will be 
ignored. 

6. An array or structure variable in a 
data list is equivalent to n items in 
the data list, where n is the number 
of element items in the array or 
structure, each of which will be asso- 
ciated with a separate use of a data 
format item. 



AB: PROCEDURE; 

DECLARE (A(6), B(7)) FIXED; 

GET FILE (X) DATA (B); 

DO I = 1 TO 6; 

A (I) = B (1*1) ♦ B CI) ; 

END; 

PUT FILE (Y) DATA (A); 

END AB; 



Input Stream 

B(l)=l, B(2)=2, B(3)=3, 

B(4)=l, B(5) = 2, B(6)=3, B(7)=t*; 

Output Stream 

A(l) = 3 A(2)=5 A(3)=*4 A(4)=3 

A(5)=S A(6)=7; 



Figure 10. Example of Data-Directed Transmission (Both Input and Output) 
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7. If a data list item is associated with 
a control format item, that control 
action is executed, and the data list 
item is paired with the next format 
item. 

8. The specified transmission is complete 
when the last item in the data list 
has been processed using its corre- 
sponding format item. Subsequent for- 
mat items, including control format 
items , are ignored, 

9. On output, data items are not automat- 
ically separated, but arithmetic data 
items generally include leading blanks 
because of data conversion rules and 
zero suppression. 

Examples : 

GET EDIT (NAME, DATA, SALARY) 

(A(N), X(2), A(6), F(6,2>); 



pm 



The 
first N 
treaded 
to NAME 
skipped 
DATA in 
charact 
opt ion a 
stant a 



EDIT (•INVENTORY^ I [ INUM, INVCODE) 
(A,F(5)>; 

first example specifies that the 
characters in the stream are to be 
as a character string and assigned 
the next two characters are to be 
the next six are to be assigned to 
character format; and the next six 
ers are to be considered as an 
lly signed decimal fixed-point con- 
nd assigned to SALARY. 



The second example specifies that the 
character string •INVENTORY^' is to be con- 
catenated with the value of INUM and placed 
in the stream in a field whose width is the 
length of the resultant string. Then the 
value of INVCODE is to be converted to 
character to represent an optionally signed 
decimal fixed-point integer constant and is 
then to be placed in the stream and is then 
to be placed in the stream right-adjusted 
in a field with a width of five characters 
(leading characters may be blanks). Note 
that operational expressions and constants 
can appear in output data lists only. 

Format Lists 

Each edit-directed data specification 
requires its own format list. 

General format: (format-list) 

where "format list* is defined as: 



i item | 

\ n item > 

(n (format-list)' 

Syntax rules: 



, item 

, n item 

, n (format-list) 



2. The letter n represents an iteration 
factor, which is either an expression 
enclosed in parentheses or an unsigned 
decimal integer constant. If it is 
the latter, a blank must separate the 
constant and the following format 
item. The iteration factor specifies 
that the associated format item or 
format list is to be used n successive 
times. A zero or negative iteration 
factor specifies that the associated 
format item or format list is to be 
skipped and not used (the data list 
item will be associated with the next 
format item). If an expression is 
used to represent the iteration fac- 
tor, it is evaluated and converted to 
an integer once for each set of itera- 
tions. The associated format item or 
format list is that item or list of 
items immediately to the right of the 
iteration factor. 

General rule: 

There are three types of format items: 
data format items, control format items, 
and the remote format item. Data format 
items specify the external forms that data 
fields are to take. Control format items 
specify the page, line, column, and spacing 
operations. The remote format item allows 
format items to be specified in a separate 
FORMAT statement elsewhere in the block. 

Detailed discussions of the various 
types of format items appear in Part II, 
Section 5, "Edit-Directed Format Items." 
The following discussions show how the for- 
mat items are used in edit-directed data 
specifications. 



Data Format Items 

On input, each 
the number of cha 
w£th the data ite 
external data. Th 
the associated va 
list, with necess 
to the attributes 
put, the value of 
the data list is 
representation sp 
and is inserted i 



data format item specifies 
racters to be associated 
m and how to interpret the 
e data item is assigned to 
riable named in the data 
ary conversion to conform 
of the variable. On out- 
the associated element in 
converted to the character 
ecified by the format item 
nto the data stream. 



1. Each "item" represents a format item 
as described below. 



There are six data format items: fixed- 
point (F), floating-point CE> , complex (C) , 
picture (P) , character-string (A), and bit- 
string (B) . They are, in general, speci- 
fied as follows: 

F (w[,d[,p]]> 

E (w,d[,sj) 

C (real-format-item (, real- format- item] ) 

P •picture-specification* 
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A [Cw)l 

B l(w)l 

In this list, the letter w represents an 
expression that specifies the number of 
characters in the field. The letter d spe- 
cifies the number of digits to the right of 
a decimal point; it may be omitted for 
integers. The real format item of the com- 
plex format item represents the appearance 
of either an F f B or P format item. The 
picture specification of the P format item 
can be either a numeric character specifi- 
cation or a character- string specification. 
On output, data associated with F and P 
format items is rounded if the internal 
precision exceeds the external precision. 

A third specification (p) is allowed in 
the F format item; it is a scaling factor. 
A third specification (s) is allowed in the 
E format item to specify the number of 
digits that must be maintained in the first 
subfield of the floating-point number. 
These specifications are discussed in 
detail in Part II, Section 5 "Edit- Directed 
Format Items." 

Note : Fixed-point binary and floating- 
point binary data items must always be 
represented in the input stream with their 
values expressed in decimal digits. The F 
and E format items then are used to access 
them, and the values will be converted to 
binary representation upon assignment. On 
output, binary items are converted to 
decimal values and the associated F or E 
format items must state the field width and 
point placement in terms of the converted 
decimal number. 

The following examples illustrate the 
use of format items: 

1. GET FILE UNFILE) EDIT C ITEM) (AC 20)'); 

This statement causes the next 20 
characters in the file called INFILE 
to be assigned to ITEM. The value is 
automatically transformed from its 
character representation specified by 
the format item A(20) f to the repre- 
sentation specified by the attributes 
declared for ITEM. 

Note : If the data list and format 
list were used for output, the length 
of a string item need not be specified 
in the format item if the field width 
is to be the same as the l»mgth of the 
string, that is, if no blanks are to 
follow the string. 

2. POT FILE (MASKFLE) EDIT (MASK) (B) J 

Assume MASK has the attribute BIT 
(25) ? then the above statement writes 
the value of MASK in the file cabled 



MASKFLE as a string of 25 characters 
consisting of f s and 1*8. A field 
width specification can be given in 
the B format item. It must be stated 
for input. 

3. PUT EDIT (TOTAL) (F(6,2)); 

Assume TOTAL has the attributes FIXED 
C4 t 2); then the above statement speci- 
fies that the value of TOTAL is to be 
converted to the character representa- 
tion of a fixed- point number and writ- 
ten into the standard output file SYS- 
PRINT. A decimal point is to be 
inserted before the last two numeric 
characters, and the number will be 
right-adjusted in a field of six char- 
acters. Leading zeros will be changed 
to blanks, and, if necessary, a minus 
sigh will be placed to the left of the 
first numeric character. 

In conversion from internal decimal 
fixed-point type to character type, 
the resultant strinq always is three 
characters longer than p, the number 
of digits in the precision specifica- 
tion of a decimal fixed-point vari- 
able. The extra characters may appear 
as blanks preceding the number in the 
converted string. And, since leading 
zeros are converted to blanks, addi- 
tional blanks may precede the number. 
If a decimal point or a minus sign 
appears, either will cause one leading 
blank to be replaced. 

In edit-directed output, the field 
width specification in the format itero 
: (in this case, the 6 in the F(6,2> 
format item) can be used to truncate 
leading zeros. In this specification, 
one zero is truncated. TOTAL would be 
converted to a character string of 
length seven. If all four digits of 
the converted number are greater than 
zero, the number, with its inserted 
decimal point, will require five digit 
positions; if the number is negative, 
another digit position will be 
required for the minus sign. Conse- 
quently, the F(6,2) specification will 
always allow all digits, the point, 
and a possible sign to appear, but 
will remove the extra blank by 
truncation. 

U. GET FILE(A) EDIT (ESTIMATE) (E(10,6)); 

This statement obtains the next ten 
characters from the file called A and 
interprets them as a floating-point 
decimal number. A decimal point is 
assumed before the rightmost six 
digits of the mantissa. An actual 
point within the data can override 
this assumption. The value of the 
number is converted to the attributes 
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of ESTIMATE and assigned to this 
variable. 



5. GET EDIT (NAME, TOTAL) 

(P f AAAA § ,P f 9999 f ) ; 

When this statement is executed, the 
standard input file SYSIN is assumed. 
The first five characters roust be 
alphabetic or blank and they are 
assigned to NAME. The next four char- 
acters must be nonblank numeric char* 
acters and they are assigned to TOTAL. 

Control Format Items 

The control format items are the spacing 
format item fX> f and the COLUMN, LINE, 
PAGE, and SKIP format items. The spacing 
format item specifies relative spacing in 
the data stream. The PAGE and LINE format 
items can be used only with PRINT files 
and, consequently, can only appear in PUT 
statements. All but PAGE generally include 
expressions. LINE, PAGE, and SKIP can also 
appear separately as options in the PUT 
statement? SKIP can appear as an option in 
the GET statement. 

The following examples illustrate the 
use of the control format items: 



PUT EDIT (• QUARTERLY STATEMENT') 

(PAGE, LINEC2), A(19>); 
PUT EDIT 

(ACCTft, BOUGHT, SOLD, 

PAYMENT, BALANCE) 
(SKIP(3), AC6), COLUMNC14), 
E(7,2), COLUMN(30), F(7 f 2>, 
COLUMN(45) , FC7,2>, 
COLUMNC60), F(7,2)); 

The first PUT statement specifies that 
the heading QUARTERLY STATEMENT is to 
be written on line two of a new page 
in the standard output file SYSPRINT. 
The second statement specifies that 
two lines are to be skipped (that is, 
"skip to the third following line") 
and the value of ACCT# is to be writ- 
ten, beginning at the first character 
of the fifth line; the value of 
BOUGHT, beginning at character posi- 
tion 1U; the value of SOLD, beginning 
at character position 30; the value of 
PAYMENT beginning at character posi- 
tion 45; and the value of BALANCE at 
character position 60. 

Note : Control format items are executed at 
the time they are encountered in the format 
list. Any control format list that appears 
after the data list is exhausted will have 
no effect. 



1. GET EDIT (NUMBER, REBATE) 

(A(5), X(5), A(5)>; 

This statement treats the next 15 
characters from the standard input 
file, SYSIN, as follows: the first 
five characters are assigned to NUM- 
BER, the next five characters are 
spaced over and ignored, and the 
remaining five characters are assigned 
to REBATE. 

2. GET FILE(IN) EDIT (MAN, OVERTIME) 

(SKIP(1), A(6>, COLUMN(60), F(4,2)>; 

This statement positions the data set 
associated with file IN to a new line; 
the first six characters on the line 
are assigned to MaN, and the four 
characters beginning at character 
position 60 are assigned to OVERTIME, 

3. PUT FILE (OUT) EDIT (PART, COUNT) 

(A(4), X(2), F(5); 

This statement places in the file 
named OUT four characters that repre- 
sent the value of PART, then two blank 
characters, and finally five charac- 
ters that represent the fixed-point 
value of COUNT. 

4. The following examples show the use of 
the COLUMN, LINE, PAGE, and SKIP for- 
mat items in combination with one 
another. 



Remote Format Item 

The remote format item (R) specifies the 
label of a FORMAT statement (or a label 
variable whose value is the label of a FOR- 
MAT statement) located elsewhere; the FOR- 
MAT statement and the GET or PUT statement 
specifying the remote format item must be 
internal to the same block. The FORMAT 
statement contains the remotely situated 
format items. This facility permits the 
choice of different format specifications 
at execution time, as illustrated by the 
following example: 

DECLARE SWITCH LABEL; 
GET FILE(IN) LIST(CODE); 
IF CODE = 1 

THEN SWITCH = LI; 

ELSE SWITCH = L2 ; 
GET FILE (IN) EDIT (W,X,Y, Z> 

(R (SWITCH)); 
LI: FORMAT (4 FC8,3>); 
L2: FORMAT (4 E(12,6)>; 

SWITCH has been declared to be a label 
variable; the second GET statement can be 
made to operate with either of the two FOR- 
MAT stat erne nt s . 

Expressions in Format Items 

The w, p, d, and s specifications in 
data format items, as well as the specifi- 
cations in control format items, need not 
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be decimal integer constants. Expressions 
are allowed. They may be variables or 
other expressions. 

On input, a value read into a variable 
can be used in a format item associated 
with another variable later in the data 
list. 

PUT EDIT (NAME, NUMBER, CITY) 
(A(N),A(N-4),A(10)); 

GET EDIT (M,STRING_A f I,STRING__B) 
(F(2),A(M),X(M),F(2),A(I)); 

In the first example, the value of NAME is 
inserted in the stream as a character 
string left-adjusted in a field of N char- 
acters; NUMBER is left-adjusted in a field 
of N-** characters; and CITY is left- 
adjusted in a field of 10 characters. In 
the second example, the first two charac- 
ters are assigned to M. The value of M is 
then taken to specify the number of charac- 
ters to be assigned to STRING A and also to 
specify the number of characters to be 
ignored before two characters are assigned 
to I, whose value then is used to specify 
the number of characters to be assigned to 
STRING B. 



PRINT FILES 

The PRINT attribute can be applied only 
to a STREAM OUTPUT file. It indicates that 
the data in the file is ultimately intended 
to be printed (although it may first be 
written on a medium other than the printed 
page). The first data byte of each record 
of a PRINT file is reserved for a ANSI 
printer control character; the compiler 
causes the control characters to be 
inserted automatically when statements con- 



taining the control options and format 
items PAGE, SKIP, and LINE are executed. 



The layout of a PRINT file can be con- 
trolled by the use of the options and for- 
mat items listed in Figure 11. (Note that 
LINESIZE, SKIP, and COLUMN can also be used 
for non-PRINT files.) LINESIZE and PAGE- 
SIZE establish the dimensions of the 
printed area of the page, excluding head- 
ings and footings. The LINESIZE option 
specifies the maximum number of characters 
to be included in each printed line; if it 
is not specified for a PRINT file, a 
default value of 120 characters is assumed 
(but there is no default for a non-PRINT 
file). The PAGESIZE option specifies the 
maximum number of lines to appear in each 
printed page; if it is not specified, a 
default value of 60 lines is assumed. 

Consider the following example: 

OPEN FILE (REPORT) OUTPUT STREAM PRINT 
PAGESIZE(55) LINESIZE( 110) ; 

This statement opens the file REPORT as a 
PRINT file. The specification PAGESIZE (55) 
indicates that each page should contain a 
maximum of 55 lines. An attempt to write 
on a page after 55 lines have already been 
written (or skipped) will raise the ENDPAGE 
condition. The standard system action for 
the ENDPAGE condition is to skip to a new 
page, but the user can establish his own 
action through use of the ON statement. 

The ENDPAGE condition is raised only 
once per page. Consequently, printing can 
be continued beyond the specified PAGESIZE 
after the ENDPAGE condition has been raised 
the first time. This can be useful, for 
example, if a footing is to be written at 
the bottom of each page. 



Option 



LINESIZE (w) * 
PAGES IZE(w) 
PAGE 
LINE(w) 
SKIPC (x)l* 



+-- 



Edit -directed 
format item 



Statement in| 
which option) 
or format ( 
item appears | 



Effect 



PAGE 
LINE(w) 
SKIPUx)]* 
COLUMN (w)* 



h 



OPEN (Establishes line width 

I 
OPEN (Establishes page length 

I 
PUT | Skip to new page 

I 

PUT (Skip to specified line 

I 
PUT (Skip specified number of lines 

I 
PUT (Skips to specified character position in line 

x . . . _. ._ 



1 Can also be used with non-PRINT files; see "Options of Transmission Statements 9 
and "Control Format Items," above, and "Line Size and Record Format, " below. 



Figure 11. Options and Format Items jror Controlling Layout of PRINT Files 
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For example; 



SKIP LIST (FOOTING) | 
PAGE; 



PUT FILE(REPORT) 

PUT FILECREPORT) 

N = N ♦ 1; 

PUT FILE(REPORT) LISTCPAGE ' ||N); 



PUT FILE (REPORT) 

END; 



SKIP (3); 



Assume that REPORT has been opened with 
PAGESIZEC55) , as shown in the previous 
example. When an attempt is made to write 
on line 56 (or to skip beyond line 55), the 
ENDPAGE condition will arise, and the begin 
block shown here will be executed. The 
first PUT statement specifies that a line 
is to be skipped, and the value of FOOTING, 
presumably a character string, is to be 
printed on line 57 (when ENDPAGE arises, 
the current line is always PAGESIZE+1K 
The second PUT statement causes a skip to 
the next page, and the ENDPAGE counter is 
automatically reset for the new page. The 
page number is incremented, and the 
character string 'PAGE' is concatenated 
with the new page number and printed. The 
final PUT statement causes three lines to 
be skipped, so that the next printing will 
be on line 4. Control returns from the 
begin block to the PUT statement that 
caused the ENDPAGE condition, and the data 
is printed. Any SKIP option specified in 
that statement is ignored, however. 

Note that SIGNAL ENDPAGE is ignored if 
there is no ENDPAGE on-unit, since it may 
not be possible for standard system action 
(start a new page) to occur (for example, 
if the file has not been opened) . 

The specification LINESIZEC 110) indi- 
cates that each line on the page can con- 
tain a maximum of 110 characters. An 
attempt to write a line greater than 110 
characters will cause the excess characters 
to be placed on the next line. 

Standard File SYSPRINT 

Unless the standard file SYSPRINT is 
declared explicitly, it is always given the 
attribute PRINT. When the file is opened, 
a new page is initiated automatically. If 
the first PUT statement that refers to the 
file has the PAGE option, or if the first 
PUT statement includes a format list with 
PAGE as the first it^m, a blank page will 
appear. 



THE ENVIRONMENT ATTRIBUTE 

The ENVIRONMENT attribute specifies 
information about the physical organization 
of the data set associated with a file. 
The information is contained in a paren- 
thesized option list; the general format 
is: 



ENVIRONMENT (option-list) 

The options applicable to stream- 
oriented transmission are: 

[record-format option) 

[BUFFERS (n) 3 

CONSECUTIVE 

LEAVE 
REWIND 

The options may appear in any order and 
are separated by blanks. The options them- 
selves cannot contain blanks. 

The options are discussed below under 
four headings: record format, buffer allo- 
cation, data set organization, and volume 
disposition. The information supplied by 
some of the options can alternatively be 
specified by default or in DDEF commands 
(see also PL/I Programmer's Guide ) . 



RECORD FORMAT 

Although record boundaries are ignored 
in strcfam-oriented transmission, record 
format is important when a data set is 
being created, not only because it affects 
the amount of storage space occupied by the 
data set and the efficiency of the program 
that processes the data, but also because 
the data set may later be processed by 
record-oriented transmission. Having spec- 
ified the record format, the user need not 
concern himself with records as long as he 
uses only stream-oriented transmission; he 
can consider his data set as a series of 
characters arranged in lines, and can use 
the SKIP option or format item (and, for a 
PRINT tile, the PAGE and LINE options and 
format items) to select a new line. 

Logical records can be in one of three 
formats: fixed-length (format-F) , 
variable-length (format-V) # or undefined- 
length (format-U), 

Record-format options for VAM data sets are; 



i F (record size) 

^ V(maximum-record~size) v 

_( U (maximum-record-size) J_ 



Record-format options for PS data sets are; 



F(block-size( , record-size} ) j 
V (maximum-block-size 

[ , max imum- record- s iz e ) ) 
U (maximum-block-si ze) 



VAM data sets and PS data sets are 
described below, under "Blocking." 



92 



Page of GC28-2045-1, Issued September 30, 197 1 by TNL GN28-1185 



Blocking 

The user's concern with blocking depends 
on the type of data set that he is using. 

Two basic types of data sets can be used 
in TSS/360: VAM data sets, and physical 
sequential (PS) data sets. VAM data sets 
are formatted for use with direct access 
devices and for interface with the TSS/360 
virtual access method (VAM) data management 
routines. PS data sets are formatted for 
use with magnetic tape or for communication 
between TSS/360 programs and programs on 
the IBM System/360 Operating System or on 
the Model 44 Programming System. Except 
when the user specifies (in the DDEF com- 
mand) that a data set is PS f TSS/36 treats 
all data sets as VAM data sets. 



deblocking information. The record size 
must never exceed the block size. For 
example, if the maximum data length antici- 
pated is 120 bytes, a block size of not 
less than 128 bytes must be specified, 
whether the records are blocked or not, 
since unblocked records are considered to 
be in blocks of one record each; if the 
records are blocked, the record size must 
not be less than 124 bytes, and must be at 
least four bytes less than the specified 
block size. 

For PS undefined-length records, all 
processing of records is the responsibility 
of the user. If a length specification is 
included in the record, the user must 
insert it himself, and he must retrieve the 
information himself. 



VAM DATA SETS : Blocking and deblocking for Note : 1« 
VAM data sets is done automatically by the 
system. The system uses page-size blocks 
(4096 bytes) , and ignores any attempt by 
the user to specify a block size. The only 1 
restriction placed on the user by the sys- I 
tern's blocking facilities is that the reco- J 
rds must stay within the specified record 
size, and format-U records must be mul- 
tiples of a page in length. 



PS DATA SETS ; For PS da 
and deblocking of fixed- 
length records is done a 
However, the block size 
(unless the records are 
record size is given by 
option) . If no record s 
specified, the records a 
unblocked (that is, each 
only one record) . Undef 
cannot be blocked by the 
their record size is not 



ta sets, blocking 

and variable- 
utomatically. 
must be stated 
unblocked and the 
the LINESIZE 
ize or line size is 
re assumed to be 

block contains 
ined-length records 

system; therefore, 

specified. 



Record format, block size, and 
record size can be specified in 
the DCB operand of a DDEF com- 
mand instead of in the ENVIRON- 
MENT attribute, but all three 
must appear together in one 
place or the other- The rele- 
vant DCB suboperands are RECFM, 
BLKSIZE, and LRECL. 

The record size for a PRINT file 
must include one byte for a 
printer control character. If 
record format, block size, and 
record size are not specified 
for a PRItfT file, the following 
default assumptions are made: 

Record format V 



Record size 125 bytes 
Line Size and Record Format 



Block size and record size are specified 
in number of bytes. 

PS fixed-length records are blocked and 
deblocked in accordance with the specified 
block size and record size. The block size 
must be an exact multiple of the record 
size. 



When variable-length record 
onto PS data sets, deblocking 
is automatically inserted into 
and block. Four bytes are pre 
data in each record to specify 
information, including two byt 
total record size; a further f 
prefixed to the first record i 
two of which specify the total 



s are written 
information 

each record 
fixed to the 

deblocking 
es for the 
our bytes are 
n each block, 

block size. 



The user of a PS data set with variable- 
length records must specify the maximum 
block size and, for blocked records, the 
maximum record size. In each case, he must 
allow an additional four bytes for the 



The record si 
can be given in 
OPEN statement. 
value specified 
the actual recor 
undefined- length 
include the four 
information in v 
For a PRINT file 
the LINESIZE opt 
the printed line 
printer control 
alent record siz 
line size for fi 
length records, 
variable-length 



ze for a STREAM OUTPUT file 
the LINESIZE option of an 

For a non-PRINT file, the 
in the LINESIZE option is 
d size for fixed-length or 
records, but does not 
bytes for deblocking 
ariable-length records. 
, the value specified in 
ion is the actual length of 
; it does not include the 
character. Thus the equiv- 
e is one byte more than the 
xed-length or undefined™ 
and five bytes more for 
records. See Figure 12. 



If the records are unblocked, it is not 
necessary to specify a block size. If the 
records are blocked, the block size roust be 
compatible with the record size: for 
fixed-length records, it must be an exact 
multiple of the record size; for variable- 
length (format-VB) records, it must be at 
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j | | format-F 1 format-V j format-U j 

H „ + — — _ — _+ +— . ~ + ■— ~ 4 



b + — ^ ,.„.+ + + 4 



PRINT file 



| Record size 1 

I 

I Block size (if not specified) 



I 



L*l 
L*l 



L*5 

L+9 



L*l 



Non-PRINT file ( 



| Record size 1 



Block size (if not specified) | L 



L+4 

L+8 

1 



L 
L 



I 

L=line size specified in LINESIZE option 

1 "Record size" here means the equivalent record size (or maximum record size in the 

cases of format-V and -U records) that would be specified in the ENVIRONMENT 

attribute 

Figure 12. Relationship Between Line Size and Record Size 



- — 4 



least four bytes larger than the maximum 
record size. 

If neither line size nor block size are 
specified for a PRINT file, a default line 
size of 120 characters is applied; there is 
no default line size for non-PRINT files.' 



BUFFER ALLOCATION 

A buffer is an internal storage area 
that is used for the intermediate storage 
of data transmitted to and from a data set. 
The use of buffers allows transmission and 
computing time to be overlapped, and it may 
help speed up processing, especially where 
the data set contains format-V or format-U 
records or where the amount of processing 
per record is irregular. Buffers are 
essential for the automatic blocking and 
deblocking of records. 

The option BUFFERS (n) in the ENVIRONMENT 
attribute specifies the number (n) of buff- 
ers to be allocated for a data set; this 
number must not exceed 255 (or such other 
maximum as was established at system 
generation) . If the number of buffers is 
not specified or is specified as zero, two 
buffers are assumed. 

The number of buffers can be specified 
in the BUFNO suboperand of a DDEF command 
instead of in the ENVIRONMENT attribute. 



DATA SET ORGANIZATION 

The organization of a data set deter- 
mines how data is recorded in the data sett 
and how the data is subseguently retrieved 
so that it can be transmitted to the pro- 



gram. The TSG/360 PL/I compiler recognizes 
two data set organizations, CONSECUTIVE and 
INDEXED. A data set that is to be accessed 
by stream-oriented transmission must have 
CONSECUTIVE organization; since this is the 
default for data set organization, it need 
not be specified at all for a STREAM file. 

The records in a CONSECUTIVE data set 
are arranged sequentially in the order in 
which they were written; they can be re- 
trieved only in the same order (unless 
record-oriented transmission is used). 
After the data set has been created, the 
associated file can be opened for input (to 
read the data), or for output (to extend 
the data set by adding records at the end, 
or to replace the contents of the data set 
by new data: the effect of using an OUTPUT 
file to process an existing data set 
depends on the DISP operand of the asso- 
ciated DDEF command) . 



VOLUME DISPOSITION 

• The volume disposition options allow the 
user to specify the action to be taken (1) 
when the end of a magnetic tape volume is 
reached and (2) when a data set on a mag- 
netic tape volume is closed normally or 
abnormally. 

The action specified by the LEAVE option 
depends on the volume position. 

l f If the end of the volume has been 

reached, no repositioning of the tape 
occurs and the channel is freed. 

2,, If a data set is closed normally or 
abnormally before the end of the 
volume, the tape is repositioned at 
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the end of the data set (unless it is 
already there) or at the end of the 
current volume if a roultivolume data 
set is being accessed. 



If neither LEAVE nor REWIND is specified 
in the options list of the ENVIRONMENT 
attribute, the tape is repositioned at the 
beginning of the current data set on the 
current volume. 



The REWIND option repositions the mag- 
netic tape to the beginning of the data 
set. 



If both LEAVE and REWIND are specified 
as options of the ENVIRONMENT attribute, 
REWIND is ignored. 
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SECTION 10: RECORD-ORIENTED TRANSMISSION 



INTRODUCTION 



The READ Statement 



This section describes the input and 
output statements used in record-oriented 
transmission, which is one of two types of 
data transmission used for input and output 
in PL/I. Those features of PL/I that apply 
equally to record-oriented and stream- 
oriented transmission, including files, 
file attributes, and opening and closing 
files, are described in Part I, Section 8, 
which forms a general introduction to this 
section and Section 9. 

In record-oriented transmission, data in 
a data set is considered to be a collection 
of records recorded in any format accept- 
able to the computer. No data conversion 
is performed during record-oriented trans- 
mission: on input, the READ statement 
causes a single record to be transmitted to 
a program variable exactly as it is record- 
ed in the data set; on output, the WRITE, 
REWRITE, or LOCATE statement causes a 
single record to be transmitted from a pro- 
gram variable exactly as it is recorded 
internally. Although data is actually 
transmitted to and from a data set in 
blocks, the statements used in record- 
oriented transmission are concerned only 
with records; the records are blocked and 
deblocked automatically. 



DATA TRANSMISSION STATEMENTS 

The following is a general description 
of the record-oriented data transmission 
statements; they are described in detail in 
Part II, Section 10, "Statements." 

The variables involved in record- 
oriented transmission must be unsub- 
scripted, of level 1 (element and array 
variables not contained in structures are 
of level 1 by default), and may be of any 
storage class. The variables cannot be 
parameters or defined variables. They can 
be label, pointer, or event variables, but 
such data may lose its validity in 
transmission. 

There are four statements that actually 
cause transmission of records to or from 
external storage. They are READ, WRITE, 
LOCATE, and REWRITE. A fifth statement, 
the DELETE statement, is used to delete 
records from an UPDATE file. The attri- 
butes of the file determine which state- 
ments can be used. 



The READ statement can be used with any 
INPUT or UPDATE file. It causes a record 
to be transmitted from the data set tc the 
progran, either directly to a variable or 
to a buffer. In the case of blocked rec- 
ords, the READ statement causes a record to 
be transferred from a buffer to the vari- 
able; consequently, every READ statement 
may not cause actual data transmission from 
the input device. 

The WRITE Statement 

The WRITE statement can be used with any 
OUTPUT file, DIRECT UPDATE file, but net 
with a SEQUENTIAL UPDATE file. It causes a 
record to be transmitted from the program 
to the data set. For unblocked records, 
transmission may be directly from a vari- 
able or from a buffer. For blocked rec- 
ords, the WRITE statement causes a logical 
record to be placed into a buffer; only 
when the blocking of the record is complete 
is there actual data transmission to the 
output device. 

The REWRITE Statement 



The REWRITE 
be replaced in 
TIAL UPDATE fi 
specifies that 
the file is to 
record irust be 
rewritten. Fo 
record can be 
has first been 



statement causes a record to 
an UPDATE file. For SEQUEN- 
les, the REWRITE statement 
the last record read from 
be rewritten; consequently a 
read before it can be 
r DIRECT UPDATE files, any 
rewritten whether or net it 
read. 



The LOCATE Statement - 

The LCCATE statement can fee used only 
with a BUFFERED OUTPUT SEQUENTIAL cr TRAN- 
SIENT file. (Note: A program that uses a 
TRANSIENT file cannot be executed on TSS/ 
360.) It allocates storage within an out- 
put buffer for a based variable, setting a 
pointer to the location in the buffer as it 
does so. This pointer can then be used to 
refer to the allocation so that data can be 
moved into the buffer. The record is writ- 
ten out automatically, during execution of 
a subsequent WRITE or LOCATE statement for 
the file, or when the file is closed. 

The DELETE Statement 

The DELETE statement specifies that a 
record in an UPDATE file be deleted. It 
can only be used for a file associated with 
an INDEXED data set. 
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The UNLOCK Statement 

The UNLOCK statement is accepted, but is 
of no significance to the TSS/360 compiler, 
since page-level interlocks are automatic- 
ally set by VIS AM data management if a file 
is opened for direct access. 



OPTIONS OF TRANSMISSION STATEMENTS 

Options that are allowed for record- 
oriented data transmission statements dif- 
fer according to the attributes of the file 
and the characteristics of the associated 
data set. Lists of all of the allowed com- 
binations for each type of file are given 
in Figures 15, and 17 later in this 
section. 

Each option consists of a keyword fol- 
lowed by a value, which is a file name, a 
variable, or an expression- This value 
must always be enclosed in parentheses. In 
any statement, the options may appear in 
any order. 

The FILE Option 

The FILE option must appear in every 
record-oriented statement. It specifies 
the name of the file upon which the opera- 
tion is to take place. It consists of the 
keyword FILE followed by the file name en- 
closed in parentheses. An example of the 
FILE option is shown in each of the state- 
ments in this section. 



The FROM Option 

The FROM option must be used in the 
WRITE statement for any OUTPUT or DIRECT 
UPDATE file. It can also be used in the 
REWRITE statement for any UPDATE file. The 
FROM option specifies the variable from 
which the record is to be written. If this 
variable is a string of varying length, the 
current length of the string determines the 
size of the record. 

For files other than DIRECT UPDATE or 
SEQUENTIAL UNBUFFERED UPDATE files, the 
FROM option can be omitted from a REWRITE 
statement. If the last record was read by 
a READ statement with the INTO option, 
REWRITE without FROM has no effect on the 
record in the data set; but if the last 
record was read by a READ statement with 
the SET option, the record will be updated, 
in the buffer, by whatever assignments were 
made. 

WRITE FILE (MASTER) FROM (MASJREC); 

REWRITE FILE (MASTER) FROM CMASJREC) ; 

Both statements specify that the value of 
the variable MASJREC is to be written into 
the file MASTER. In the case of the WRITE 
statement, it specifies a new record in a 
SEQUENTIAL OUTPUT file. The REWRITE state- 
ment specieies that MASJREC is to replace 
the last record read from a SEQUENTIAL UP- 
DATE file. 



The INTO Option 

The INTO option can be used in the READ 
statement for any INPUT or UPDATE file. 
The INTO option specifies a variable to 
which the logical record is to be assigned. 

READ FILE (DETAIL) INTO (RECORDED; 

This specifies that the next sequential 
record is to be assigned to the variable 
RECORD_l . 

Note that the INTO option can name an 
element string variable of varying length; 
thus it is possible to read a record whose 
length is unknown to the PL/I user, and is 
not contained in the data. The current 
length of the string is set to the length 
of the record. The LENGTH built-in func- 
tion can be used to find the length of the 
record. 

When the record variable of a READ sta- 
tement is a variable length L it-string, the 
byte count, and not the bit count, is 
stored as the current length. *£his is an 
implementation restriction because all 
variable length bit-strings are not both 
byte aligned and multiples of eight* 



The SET Option 

The SET option can be used with a READ 
statement or a LOCATE statement. It speci- 
fies that a named pointer variable is to be 
set to point to the location in the buffer 
into which data has been moved during the 
READ operation, or which has been allocated 
by the LOCATE statement. 

READ FILE (LIST) SET (P); 

This statement specifies that the value of 
the pointer variable P is to be set to the 
location in the buffer of the next sequen- 
tial record. 

The IGNORE Option 

The IGNORE option can be used in a READ 
statement for any SEQUENTIAL INPUT or UP- 
DATE file. It includes an expression whose 
integral value specifies a number of rec- 
ords to be skipped over and ignored. 

READ FILE (IN) IGNORE (3); 

This statement specifies that the next 
three records in the file are to be 
skipped . 
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If a READ statement includes none of the 
options INTO, SET, and IGNORE, IGNORE (1) is 
assumed. 

The ¥.m ...Opt ion 

The KEY option applies only to KEYED 
files associated with data sets of INDEXED 
organization, (The types of data set 
organization applicable to record-oriented 
transmission are discussed under "Data Set 
Organization, * below.) The option consists 
of the keyword KEY followed by a parenthe- 
sized expression, which may be a character- 
string constant, a variable, or any other 
element expression ; if necessary, the 
expression is evaluated and converted to a 
character string. The rules governing the 
length of the character string and what it 
represents are discussed below under "IN- 
DEXED Organization. 11 

The KEY option identifies a particular 
record. It can be used in a READ statement 
for an INPUT or UPDATE file, or in a 
REWRITE or DELETE statement for a DIRECT 
UPDATE file. (The KEY option can be used , 
in a READ statement for a SEQUENTIAL file 
only if the associated data set has INDEXED 
organization. ) 



READ FILE (STOCK) 
KEY (STKEY); 



INTO (ITEM) 



This statement specifies that the record 
identified by the character- string value of 
the variable STKEY is to be assigned to the 

variable ITEM* 

The KEYFROM and KEYTO Options 

The KEYFROM and KEYTO options apply only 
to KEYED files associated with data sets of 
INDEXED organization. Each option consists 
of the keyword KEYFROM or KEYTO followed by 
a parenthesized expression. For KEYFROM r 
the expression may be a character- string 
constant, a variable, or any other element 
expression; if necessary, the expression is 
evaluated and converted to a character 
string* For KEYTO, the expression must be 
a character-string variable* The rules 
governing the lengths of the character 
strings and what they represent are dis- 
cussed below, under "INDEXED Organization. " 

The KEYFROM option specifies the loca- 
tion within the data set where the record 
is to be written. It can be used in a WRITE 
statement for a RECORD OUTPUT or DIRECT UP- 
DATE file, or in a LOCATE statement. 

WRITE FILE (LOANS) FROM (LOANREC) 
KEYFROM (LOANNO); 

This statement specifies that the value of 
LOANREC is to be written as the next- record 
in the file LOANS, and that the value of 
LOANNO is to be used as the key. 



The KEYTO option specifies the name of 
the variable to which the key of the record 
being read is to be assigned* It can be 
used in a READ statement for a SEQUENTIAL 
INPUT or SEQUENTIAL UPDATE file. 

READ FILE (DETAIL) INTO ( INVTRY) 
KEYTO CKEYFLD); 

This statement specifies that the next 
record in the file DETAIL is to be assigned 
to the variable INVTRY, and that the key of 
the record is to be assigned to the vari- 
able KEYFLD. 



The EVENT Option 

The EVENT option is specif ied "with the 
keyword EVENT followed by the parenthesized 
name of an event variable. (The appearance 
of a name in the EVENT option constitutes a 
contextual declaration of an event vari- 
able.) The option can appear in any READ, 
WRITE, REWRITE, or DELETE statement for an 
UNBUFFERED file. 

The EVENT option is designed to be used 
when asynchronous I/O operation is possi- 
ble. In TSS/360, the user's execution is 
suspended while I/O is in progress, except 
for CONSECUTIVE SEQUENTIAL UNBUFFERED. 
Only in this case is asynchronous I/O pos- 
sible. Thus, when a WAIT statement is 
encountered, I/O is generally complete, so 
that this option is of little value to the 
TSS/360 PL/I user. 

The EVENT option also specifies that 
record I/O interruptions (except for UNDE- 
FINEDF1LE) are not to occur until a WAIT 
statement, specifying the same event vari- 
able, is executed by the same task. For 
example: 

READ FILE (MASTER) INTO <REC_VAR) 
EVENT (RECORDED ; 



WAIT (RECORDJL) ; 

In this exa^jle, when the READ statements is 
executed, the input operation is started. 
No I/O interruption for RECORD, TRANSMIT, 
KEY, or ENDFILE conditions will take place 
until the WAIT statement is executed. If, 
when the WAIT statement is executed, the 
input operation is not complete (possible 
only for CONSECUTIVE SEQUENTIAL UNBUFFERED 
files), and if none of the four conditions 
is raised, inline processing stops, but the 
operation continues. When the operation is 
successfully completed , processing con- 
tinues with the next statement following 
the WAIT statement. If any of the four 
conditions arise during execution of the 
READ statement, an interruption will occur 
when the WAIT statement is executed. On- 
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units will be entered in the order in which 
the interruptions occur (normally, TRANSMIT 
or ENDFILE, KEY, RECORD). Then upon normal 
return froir all of the on-units thus 
entered, processing continues with the next 
statement following the WAIT statement- 
Note that although the EVENT option 
specifies asynchronous processing, it does 
not specify that interruptions will be 
caused asynchronously; none of the four 
conditions can cause an interruption until 
they are synchronized with processing by 
the WAIT statement. 



files. Which irode is used is determined by 
the data transmission statements and 
options specified by the user. 
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Once a statement containing an EVENT 
option has been executed, the event vari- 
able named in the option is considered to 
be active; while it is active, the event 
variable cannot ne specified again in an 
EVENT option. The event variable becomes 
inactive again only after execution of the 
corresponding WAIT statement. 

An input/output event should fce waited 
for only by the task that initiated the 
input /out put operation. 

The NOLQCK Option 

The NOLOCK option is ignored, since 
page-level interlocks are automatically set 
by VISAM data management if a file is 
opened for direct access. 



PROCESSING MODES 

Record-oriented transmission offers the 
user alternative methods of nandling his 
data. He can process data within the 
storage area allocated to his program? this 
is termed tie move mode because the data is 
actually moved into or out of program 
storage either directly or via a buffer. 
Alternatively, the user can process his 
data while it remains in a buffer (that is, 
without moving it into the storage area 
allocated to his program) ; tnis is termed 
tne locate mode , because the execution of a 
data transmission statement merely identi- 
fies the location of the storage allocated 
to a record in the buffer. The locate mode 
is applicable only to EUFFERED SEQUENTIAL 



WOVE MODE 

In the move mode, a 
causes a record to be t 
external storage to the 
the INTO option (via an 
EUFFERED file is used); 
statement causes a reco 
from the variable named 
to external storage (pe 
buffer) . The variables 
and FROM options can be 
class. 



READ statement 

ransferred from 
variable named in 
input buffer if a 
a WRITE or REWRITE 

rd to be transferred 
in the FROM option 

rhaps via an output 
named in the INTO 
of any storage 



Consider the following example, which is 
illustrated in Figure 13: 

NEXT: READ FILECIN) INTO(DATA); 



WRITE FILE (CUT) FROM (DATA), 
GO TO NEXT; 




1ST / j 2ND\ 3RD 

write' 'v.'riteV write 



OUTPUT 
BUFFER 




Figure 13. Input and Output: Move Mode 
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The first time the READ statement is 
executed, a fclock is transmitted from the 
data set associated with the file IN to an 
input buffer, and the first record in the 
block is assigned to the variable DATA; 
further executions of the READ statement 
assign successive records from the buffer 
to DATA. When the buffer is empty, the 
next READ statement causes a new block to 
be transmitted from the data set. The 
WRITE statement is executed in a similar 
manner, building physical records in an 
output buffer and transmitting them to the 
data set associated with the file OUT each 
time the buffer is filled. 



The move mode may be simpler to use than 
the locate mode since there are no buffer 
alignment problems. Furthermore, it can 
result in faster execution when there are 
numerous references to the contents of the 
same record, because of the overhead 
incurred by the indirect addressing tech- 
nique used in locate mode. 



LOCATE MODE 



Figure 14 illustrates the following 
example, which uses locate mode for input 
and move mode for output: 



DCL DATA BASED (P> ; 



NEXT: READ FILE(IN) SETCP); 



WRITE FILE (OUT) FROM DATA); 
GO TO NEXT; 

The first time the READ statement is 
executed, a fclock is transmitted from the 
data set associated with the file IN to an 
input buffer, and the pointer variable P is 
set to point to the first record in the 
buffer; any reference to the variable DATA 
or to any other based variable qualified by 
the pointer P will then in effect be a 
reference to this first record. Further 
executions of the READ statement set the 
pointer variable P to point to succeeding 
records in the buffer- When the buffer is 
empty, the next READ statement causes a new 
block to be transmitted from the data set. 



Locate mode requires the use of based 
variables. A based variable is effectively 
overlaid on the data in the buffer, and 
different based variables can be used to 
access the same data by associating the 
same pointer with each one; thus the same 
data can be interpreted in different ways. 
Locate mode can also be used to read self- 
defining records, in wnich information in 
one part of the record is used to indicate 
the structure of the rest of the record; 
for example, this information could be a 
count of the number of repetitions of a 
subfield, or a code identifying which one 
of a class of structures should be used to 
interpret the record. 



DATA 
SET 
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OUTPUT 

BUFFER 



Locate mode frequently provides faster 
execution than move since there is less 
movement of data, and less storage may be 
required. But it must be used carefully; 
in particular, the user must be aware of 
how his data will be aligned in the ouffer 
and how structured data will be mapped; 
structure mapping and data alignment are 
discussed in Part II, Section 11. 
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It is doubtful whether the uuo of locate 
mode for both input and output in the above 
example would result in increased offici en- 
cry. An alternative would be to use move 
mode tor input and locate mode for output, 
tor example*: 

DCL DATA BASED(P); 



[record- format option! 
(BUFPERMn) 1 



NEXT: LOCATE DATA 
READ FILECIN) 



GO TO NEXT; 



FILE (OUT) ; 
INTO (DATA) , 



Each execution of the LOCATE statement 
reserves storage in an output buffer for a 
new allocation of the based variable DATA 
and sets the pointer variable P to point to 
this storage. The first execution of the 
READ statement causes a block to be trans- 
mitted from the data set associated with 
the file IN to an input buffer, and the 
first record in the block to be assigned to 
the first allocation of DATA; subsequent 
executions of the READ statement assign 
successive logical records to the current 
allocation of DATA. When the input buffer 
is empty, the next READ statement causes a 
new block to be transmitted from the data 
set. Each record is available for proces- 
sing during the period between the execu- 
tion of the READ statement and the next 
execution of the LOCATE statement. When no 
further space is available in the output 
buffer, the next execution of the LOCATE 
statement causes a block to oe transmitted 
to the data set associated with the file 
OUT, and a new buffer to be allocated. 

Note that, in each of the foregoing 
examples, if the data set accessed in the 
move mode had had unblocked records and the 
associated file had been declared UNBUF- 
FERED, movement of data in internal storage 
may have been unnecessary; if possible, 
each record would have been read into and 
written from the same buffer. 



THE ENVIRONMENT ATTRIBUTE 

The ENVIRONMENT attribute can be speci- 
fied only in a DECLAJRE statement; it cannot 
be specified as an option of an OPEN state- 
ment. It specifies information about the 
physical organization of the dat£ set asso- 
ciated with a file. The information is 
contained in a parenthesized option list; 
the general format is: 

ENVIRONMENT (option- list I 

The options applicable to record- 
oriented transmission, with the exception 
of teleprocessing applications, are: 



[l 



} CONSECUTIVE / " 


) INDEXED \ 


j LEAVE ( 




| REWIND (_ 




| CTLASA ' 




/CTL360 \_ 





[COBOL) 

[NCP {decimal- integer- constant ) ) 

[TKKOFLJ 

Note : The INDEXAREA and NOWRITE options 
are ignored in TSS/360. 

The option:; may appear in any order, and 
are separated by blanks. The options them- 
selves cannot contain blanks. 

The options are discussc?d below under 
eleven headings: record format, buffer 
allocation, data set organization, volume 
disposition, carriage control, data inter- 
change, data management optimization, key 
classification, asynchronous operations 
limit, and track overflow. The information 
supplied by some of the options can alter- 
natively be specified in a DDEF command or 
by default. The DDEF command is described 
in IBM System/36 Time Sharing System: 
PL/I Programmer's Guide . 



RECORD FORMAT 

Logical records can be in one of three 
formats: fixed-length (f ormat-F) , 
variable-length (format-V), and undefined- 
length length (format U) . 

Record-format options for VAM data sets are; 



I 



F (record size) 

V (maximum- record- size) 

U (maximum-record-size) 



Record-format options for PS data sets ax*. 



F (block- size I, record-si zeC) j 
V (maximum- block-size 

(, maximum- record -size] ) 
U (maximum- block-size) 



VAM data sets and PS data sets are 
described below, under "Blocking.* 

Blocking 

The user's concern with blocking depends 
on the type of data set that he is using. 
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Two basic types of data sets can be used 
in TSS/360: VAM data sets, and physical 
sequential (PS) data sets. VAM data sets 
are formatted for use with direct access 
devices and for interface with th<» TSS/360 
virtual access method CVAM) data management 
routines. PS data sets are formatted for 
use with magnetic tape or for communication 
between TSS/360 programs and programs on 
the IBM System/ 360 Operating System or on 
the Model 44 Programming System. Except 
when the user specifies (in the DDEF com- 
mand) that a data set is PS, TSS/360 treats 
all data sets as virtual storage data sets. 



For undefined-length ( format ~U) records, 
ail processing of records is the responsi- 
bility of the user. If a length specifica- 
tion is included in the record, the user 
must insert it himself, and he must re- 
trieve the information himself. 

Record format, block size, and record 
size can be specified in the DCB operand of 
a DDEF command instead of in the ENVIRON- 
MENT attribute, but all three must appear 
together in one place or the other. The 
relevant DCB suboperands are RECFM, 
BLKSIZE, and LRECL. 



VIRTUAL STORAGE DATA SETS : Format- F, -V, 
and -U records are permitted. Blocking and 
deblocking are done automatically by the 
system. The system uses page-size blocks 
(4096 bytes), and ignores any attempt by 
the user to specify a block size. Records 
must stay within the specified record size f 
and format-U records must be multiples of a 
page in length. 

PS DATA SETS : Format-F, -V, and -U records 
are permitted. The block size and record 
size are specified in number of bytes. • The 
block size must always be stated; if no 
record size is specified, the records are 
assumed to be unblocked (that is, each 
block contains only one record). 
Undefined- length records cannot be blocked; 
therefore, the record size can be specified 
for fixed-length and variable-length rec- 
ords only. Blocking and deblocking of 
fixed-length and variable- length records 
are handled automatically. 

Fixed-length (format-F) records are 
blocked and deblocked in accordance with 
the specified block size and record size. 
The block size must be an exact multiple of 
the record size. 



PUFFER ALLOCATION 

A buffer is <in internal storage area 
that is used for the intermediate storage 
of data transmitted to and from a data set. 
The use of buffers allows transmission and 
computing time to be overlapped, and it may 
help speed up processing, especially where 
the amount of [recessing per record is 
irregular. Buffers are essential for the 
automatic blocking and deblocking of rec- 
ords and for locate-mode transmission. 

The option BUFFERS (n) in the ENVIRONMENT 
attribute specifies the number (n) of buf- 
fers to be allocated for a data set; this 
number must not. exceed 255 (or such other 
maximum as was established at system 
generation). If the number of buffers is 
not specified for a BUFFERED file or is 
specified as zero, two buffers are assumed. 

The number of buffers can be specified 
in the BUFNO suboperand of a DDEF command 
instead of in the ENVIRONMENT attribute. 



DATA SET ORGANIZATION 



When variable-length Cformat-V) records 
are written, deblocking information is 
automatically inserted into each record and 
block. Four bytes are prefixed to the data 
in each record to specify deblocking infor- 
mation, including two bytes for the total 
record size; a further four bytes are pre- 
fixed to the first record in each block, 
two of which specify the total block size. 

For format-V records, the user must spe- 
cify the maximum block size and, for 
blocked records, the maximum record size; 
in each case, he must allow an additional 
four bytes for the deblocking information. 
The record size must never exceed the block 
size. For example, if the maximum data 
length anticipated is 120 bytes, the maxi- 
mum record size should be specified as 12** 
bytes, and a block size of not less than 
128 bytes should be specified whetuer the 
records are blocked or not (unblocked rec-r 
ords are considered to be in blocks of one 
record each) . 



The organization of a data set deter- 
mines how data is recorded in a data set 
volume, and how the data is subseguently 
retrieved so that it can be transmitted to 
the program. Records are stored in and re- 
trieved from a data set either sequentially 
on the basis of successive physical posi- 
tions, or directly by the use of keys spe- 
cified in data transmission statements. 
These storage and retrieval methods provide 
PL/I with two general data set organiza- 
tions: CONSECUTIVE and INDEXED: CONSECU- 
TIVE is assumed by default if no data set 
organization is specified. 
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sequence, and indexes, created and main- 
tained by the system, are used tor retriev- 
al at records. 

CONSECUTIVE data sets are the simpler of 
the two t yj>es to create and use, and they 
have the advantage that less internal and 
external storage is required. However, 
records in a CONSECUTIVE data set can be 
updated only in their existing sequence, 
and if records are to be inserted a new 
data set must be created. Even sequential 
updating is not supported for magnetic 
tape. 



if both LEAVE and REWIND are specified 
as options of the ENVIRONMENT attribute, 
KEWJNU is ignored. 



PHINTER/PUNCH roNTKOI, 

The piint er/punch control options CTLASA 
and CTLJ60 apply only to OUTPUT files asso- 
ciated with CONSECUTIVE data sets. They 
specify that the first character of a rec- 
ord is to be interpreted as a control 
character . 



Although an INDEXED data set must be I 1. 
created sequentially, once it t«xists roc- I 
ords can be retrieved, updated, added, or 
deleted at random. Sequential processing 
of an INDEXED data set is slower than that 2. 
of a corresponding CONSECUTIVE data set., 
because the records it contains are not 
necessarily arranged in physical sequence 
but are logically chained in order of 
ascending key values. An INDEXED data set 

can contain only format-F or format-V ree- INTERCHANGE 
ords; format-U records are not supported. PROGRAMS 



The? CTLASA option sp€±cifies American 
National Standard FORTRAN control 
characters. 

The CTL160 option specifies IBM 
System/ *60 machine code control 
charact ers . 



OF DATA BETWEEN COBOL AND PL/I 



The use of the record-oriented transmis- 
sion statements to process data sets of 
each type of organization is discussed 
under appropriate headings below. 



The COBOL option in the ENVIRONMENT 
attribute specifies that the file will con- 
tain structures mapped according to the 
COBOL (F) algorithm. This type of file is 
subject to the following restrictions: 



VOLUME DISPOSITION 



1. The file c\m be- used only for READ 
INTO ami WHITE FROM statements. 



The volume disposition option allows the 
user to specify the action to be taken (1) 
when the end of a magnetic tape volume is 
reached and (2) when a data set on a mag- 
netic tape volume is closed normally or 
abnormally. 

The action specified by the LEAVE option 
depends on the volume position. 



The 
the 



EVENT o[tion cannot 
above statements. 



be used with 



It cm ON-condition arises as a result 
ot t he HEAD INTO statement, the vari- 
able named in the INTO option cannot 
be used in the on- unit , and return 
from t he on-unit must be normal if the 
completed variable is required. 



If the end of the volume has been 
reached, no repositioning of the tape 
occurs and the channel is freed. 



The iile name cannot be passed as an 
argument . 



2. If the data set is closed normally or 
abnormally before the end of the 
volume, the tape is repositioned at 
the end of the data set (unless it is 
already there) or at the end of the 
current volume if a multivolume data 
set is being accessed. 

The REWIND option repositions the mag- 
netic tape to the beginning of the data 
set. 

If neither LEAVE or REWIND is specified 
in the options list of the ENVIRONMEOT 
attribute, the tape is repositioned at the 
beginning of the current data set on the 
current volume. 



ASYNCHRONOUS OPERATIONS LIMIT 

The asynchronous operations limit speci- 
fies the number of incomplete I/O opera- 
tions, with the EVENT option that are 
allowed to exist for the file at one time. 

The decimal integer constant specified 
with NCP must have a value in the range 1 
through 99; otherwise, 1 is assumed and an 
error message is issued. 

This opt ion is equivalent to the NCP 
suboperand ot the DCn operand of the DDEF 
command. Stn» Appendix D of PL/I Program- 
mer's Guide. 
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Note s Use of the NCP option is valid only 
for PS data sets accessed by USAM (i.e., 
CONSECUTIVE SEQUENTIAL UNBUFFERED tiles). 



data transmission statements and options 
that can he used to create and access a 
CONSECUTIVE f\ai a set. 



TRACK OVERFLOW 

The track overflow option s pecifies that 
records transmitted to a direct-access 
storage device can be written on overflow 
tracks if necessary. 

This option is equivalent to the specif- 
fication of W T" in the RECFM subparameter 
of the DCB parameter of the DDEF command. 



CONSECUTIVE ORGANIZATION 

In a data set with CONSECUTIVE organiza- 
tion, the records have no keys. When the 
data set is created, records are written 
consecutively in the order in which they 
are presented. The records can be re- 
trieved only in the order in which they 
were written or in the reverse order; 
therefore, the associated file must have 
the SEQUENTIAL attribute. A CONSECUTIVE 
data set can have format-F, format-V, or 
format -U records. 



Note the difference 
TIVE option of the ENV 
and the SEQUENTIAL att 
specifies the physical 
data set; SEQUENTIAL s 
is to be processed. A 
CUTIVE organization mu 
a SEQUENTIAL file; but 
DEXED organization can 
either a SEQUENTIAL or 



between the CONS ECU - 
IRONMENT attribute 
ribute. CONSECUTIVE 

organization of a 
pecifies how a file 

data set with CONSE- 
st be associated with 

a data set with IN- 

be associated with 

DIRECT file. 



A CONSECUTIVE data set on magnetic tape 
can be read forwards or backwards. If the 
data set is to be read backwards, the asso- 
ciated file must have the BACKWARDS attri- 
bute- If a data set is first read or writ- 
ten forwards and then read backwards in the 
same program, the LEAVE option should be 
specified in the ENVIRONMENT attribute to 
prevent normal rewind when the file is 
closed (or, with a multivolume data set, 
when volume-switching occurs). Variable* 
length records cannot be read backwards. 

Once a CONSECUTIVE data set has been 
created, the file that accesses it can be 
opened for SEQUENTIAL INPUT or SEQUENTIAL 
OUTPUT; or it can be opened for SEQUENTIAL 
UPDATE, provided that the data set is on a 
direct-access storage device. If it is on 
magnetic tape and opened for OUTPUT, DISP= 
MOD must be specified in the DDEF command; 
records can then be added to the end of the 
data set. (If DISP=MOD is not specified 
for a CONSECUTIVE data set that is already 
created and on magnetic tape, the data set 
will be overwritten.) Figure 15 lists the 



SEQUENTIAL UPDATE 

When a consecutive data set is accessed 
by a SEQUENTIAL UPDATE file, a record must 
be retrieved with a READ statement before 
it can be updated by a REWRITE statement? 
however, every record that is retrieved 
need not be rewritten. A REWRITE statement 
will always update the last record read. 

Consider the following: 

READ FILE(F) INTO* A); 



READ FILE(F) INTO(B); 



REWRITE FILE(F) FROM(A); 

The REWRITE statement updates the record 
which was read by the second READ state- 
ment. The record that was read by the 
first statement cannot be rewritten after 
the second READ statement has been 
executed . 

Intervening READ statement's are not per- 
mitted between a READ statement and a 
REWRITE statement that refer to the same 
record in a data set. For example, the 
following is not valid: 

READ FILE (F) INTO (A) EVENT (El); 



READ FILE CF> INTO (B) EVENT (E2>; 



WAIT CE1); 

REWRITE FILE <F> FROM (A) ; 

The REWRITE statement will attempt to 
update the last record read, which, in this 
instance, is the record read by the first 
READ statement. (A record accessed by a 
READ statement with the EVENT option is not 
considered to have been read until the 
corresponding WAIT statement has been 
executed.) Because of the intervention of 
the second READ statement, the ERROR condi- 
tion will be raised. 



INDEXED ORGANIZATION 

Since a data set with INDEXED organiza- 
tion is a VAM data set Cof the virtual in- 
dexed type), it must be on a direct access 
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File declaration 1 



Valid statements, with options that must 

appear 



Other options that can 
also be used 



SEQUENTIAL OUTPUT 
BUFFERED 



WRITE FILE (file-name) FROM( variable) ; 
LOCATE variable FILEC file-name) ; 



SET (pointer-variable) 



SEQUENTIAL OUTPUT 
UNBUFFERED 



WRITE FILE (file-name) FROM (variable) ; 



EVENT ( event-variable) 



SEQUENTIAL INPUT 
BUFFERED 



READ FILE (file-name) INTO (variable) ; 

READ FILE (file-name) SET (pointer-variable) ; 

READ FILE (file-name) IGNORE (expression) ; 



SEQUENTIAL INPUT 
UNBUFFERED 



READ FILEC file-name) INTO (variable ; 
READ FILE ( file-name) IGNORE (expression) ; 



EVENT (event-variable) 
EVENT (event-variable) 



SEQUENTIAL UPDATE 
BUFFERED 



READ FILE (file-name) INTO (variable) ; 
READ FILECf ile-naire SET (pointer-variable) ; 
READ FILE (file-name) IGNORE (expression) ; 
REWRITE FILE (file-name) j 



FROM(variable) 



SEQUENTIAL UPDATE 
UNBUFFERED 



h 



READ FILEC file-name) INTO (variable) ; 
READ FILECf ile-name) IGNORE (expression) 
REWRITE FILE(fiie-name) FROM (variable) ; 



EVENT (event-variable) 
EVENT (event-variable) 
EVENT (event-variable) 



1 The complete file declaration would include the attributes FILE, RECORD, and 
ENVIRONMENT (CONSECUTIVE) , for example: 

DECLARE MASTER FILE RECORD SEQUENTIAL OUTPUT BUFFERED ENVIRONMENT (CONSECUTIVE) ; 

By omitting the attributes that would be applied by default, this can be shortened tc: 

DECLARE MASTER FILE RECORD OUTPUT; 

Figure 15. Statements and Options Permitted fcr Creating and Accessing CONSECUTIVE Data 
Sets 



device. Its records are arranged in logic- 
al sequence according to keys that are 
associated with each record, A key is a 
character string that usually represents an 
item within the record, such as a part 
number, a date, or a name. Logical records 
are arranged in the data set in ascending 
key sequence according to the System/360 
collating sequence. Indexes included in 
the data set are used by the operating sys- 
tem data-management routines to locate a 
record when the key is supplied. Format-V 
and format -F records can be used in an IN- 
DEXED data set. 

Unlike CONSECUTIVE organization, INDEXED 
organization does not require every record 
to be accessed in sequential f r shion. Once 
an INDEXED data set has teen created, the 
associated file may have the attribute 



SEQUENTIAL or DIRECT as well as INPUT or 
UPDATE. The INDEXED data set's records can 
be retrieved, deleted, and replaced at ran- 
dom, or added to the end of the data set. 
If the associated file has the DIRECT 
attribute, records can also be inserted at 
random. 

An INDEXED data set can be accessed ran- 
domly (i.e., nonsequentially), whether its 
associated file is SEQUENTIAL or DIRECT. 
The differences are: 

• A SEQUENTIAL file is more efficient, if 
the records are generally accessed in 
physical sequence. 

• A SEQUENTIAL file allows either sequen- 
tial (no keys specified) or random 
(keys specified) access; all I/O state- 
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ments used with a DIRECT file must spe- 
cify a key. 

• Only a DIRECT file can be used to add 
records at random. With a SEQUENTIAL 
file, records can only he added to the 
end of the data set, or replaced (not 
inserted) . 

• Only a DIRECT file causes the setting 
of an interlock while a data set is 
being updated. (An interlock is a pro- 
gramming device that allows a data set 
to be updated without interference from 
other users who have been given access 
to the data set.) 

• For cases where a KEY f KEYTO, or KEY- 
FROM option is in error, the PL/I 
library gives more complete diagnostic 
facilities if the DIRECT file is being 
used. 

Figure 17 lists the data-transmission 
statements and options that can be used to 
create and access an INDEXED data set. 



KEYS 

There are two kinds of keys r recorded 
keys and source keys. A recor ded key is a 
character string that actually appears with 
each record in the data set to identify 
that record; its length cannot exceed 255 
characters. A source key is the character- 
string value of the expression that appears 
in the KEY or KEYFROM option of a data 
transmission statement to identify the 
statement to which the record refers; for 
direct access of an INDEXED data set, each 
transmission statement must include a 
source key. 

The length of the recorded keys in an 
INDEXED data set is defined by the KEYLEN 
suboperand of the DDEF command that defines 
the data set. If the length of a source 
key differs from the specified length of 
the recorded keys, the source key is trun- 
cated on the right or padded with blanks on 
the right to the specified length. 

Since the GENKEY (generic key) option is 
not supported by TSS/360 data management, 
all source keys should have the length spe- 
cified in the KEYLEN suboperand of the 
DDEF command. If a record with a matching 
key is not found, the KEY, condition is 
raised and the data set is positioned to 
the first record. 

The recorded keys in an INDEXED data set 
may be separate from, or embedded within, 
the logical records. The RKP suboperand of 
the DDEF command determines how the key is 
to be maintained. (See Figure 16.) This 
suboperand specifies the displacement, in 
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Figure 16. Relationship Between RKP Sub- 
operand and Record Format 



bytes, of the key from the beginning of the 
record. The library maintains the key as 
an initial (non-embedded) key if RKP equals 
zero, for format-F records, or if RKP 
equals four, for forma t-V records. The 
library maintains the key as part of the 
data if RKP is not zero, for format-F rec- 
ords, or if RKP is greater than four, for 
format-V records. Maintaining the key as 
part of the data means that the user must 
ensure that the key is in position before 
the record is written; on input, the KEYTO 
option can be used to obtain a copy of the 
key. 

The use of embedded keys obviates the 
need for the KEYTO option during sequential 
input, but the KEYFROM option is still 
required for output. (However, the data 
specified by the KEYFROM option may be the 
embedded key itself.) 

During the execution of a LOCATE or 
WRITE statement that adds a record to a 
data set with embedded keys, the value of 
the expression in the KEYFROM option is 
compared with the key embedded in the rec- 
ord; if they do not match, the KEY condi- 
tion is raised. When the KEY condition is 
raised in this way by a LOCATE statement, 
the record in the buffer cannot be trans- 
mitted until the key embedded in the record 
has been changed to match the value given 
in the KEYFROM option; if the file is 
closed 3 - before the key has been corrected, 
the key supplied in the KEYFROM option is 
automatically substituted for the embedded 
key, and the record is then transmitted. 



*Tn these circumstances, the file cculd not 
be closed explicitly (i.e., by a CLOSE 
statement) but only implicitly on termina- 
tion of the task that opened the file. 
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File declaration 1 



Valid statements, with options that must 
appear 



Other options that can 
also be used 



SEQUENTIAL OUTPUT 
BUFFERED 2 



WRITE FILE C file-name) FROM( variable) 

KEYFROjv (expression) ; 

LOCATE variable FILE (f i le-name) 
KEYFROM(expression) ; 



SET (pointer- variable) 



SEQUENTIAL INPUT 
BUFFERED 2 



READ FIIECf ile-name) INTO (variable) ; 



READ FILE(f ile-name) SET (pointer-variable) ; 



READ FILE (file-name) IGNORE (expression) ; 



KEY (expression) or KEYTO 
(character-string- 
variable) 

KEY (expression) or KEYTO 
( character-string- 
variable) 



SEQUENTIAL UPDATE 
BUFFERED 2 



READ FILE(file-name) INTO (variable) ; 

READ FILE(f ile-name) SET ( pointer-variable) ; 

READ FILE( file-name) IGNORE (expression) ; 
REWRITE FILE( file-name) ? 
DELETE FILE(f ile-name) ? 



KEY (expression) or KEYTO 

( character-string- 
variable) 

KEY(expression) or KEYTO 
(character-string- 
variable) 



FRON(variable) 



h 



DIRECT OUTPUT 



h 



WRITE FILE (file-name) FROM (variable) 
KEYFROM( expression) ; 



EVEOT( event-variable) 3 



DIRECT INPUT 



h 



READ FILE (file-name) INTO (variable) 
KEY(expression) ; 



EVENT ( event- variable) 3 



DIRECT UPDATE 



h 



READ FILE (file-name) INTO (variable) 
KEY( expression) ; 

REWRITE FILE( file-name) FROM (variable) 
KEY (expression) ; 

WRITE FILE (file-name) FROM (variable) 
KEYFROM( expression) ; 

DELETE FILE(f ile-name) KEY ( expression) ; 



EVENT ( event- variable) 3 



EVENT (event-variable) 3 



EVENT (event- variable) 3 



EVENT (event-variable) 3 



*The complete file declaration would include the attributes FILE, RECORD, and ENVIRON- 
MENT (INDEXED); if any of the options KEY, KEYFROM, and KEYTO is used, it must also 
include the attribute KEYED, For example: 

DECLARE MASTER FILE RECORD SEQUENTIAL OUTPUT BUFFERED KEYED ENVIRONMENT ( INDEXED) ; 

By omitting the attributes that would be applied by default, this can be shortened to: 

DECLARE MASTER FILE RECORD KEYED ENVIRONMENT (INDEXED) ; 

2 If a SEQUENTIAL file associated with an INDEXED data set is declared UNBUFFERED, the 
compiler will change the declaration to BUFFERED. Thus a declaration of UNBUFFERED 
gains nothing. 

3 Use of the EVENT variable with DIRECT files is supported by TSS/360 for compatibility 
only; in TSS/360, asynchronous I/O can occur only with CONSECUTIVE SEQUENTIAL UNBUF- 
FERED files. 

Figure 17. Statements and Options Permitted for Creating and Accessing INDEXED Data 
Sets 
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CREATING A DATA SET 

When an INDEXED data set 
created, if the associated 
for SEQUENTIAL OUTPUT, the 
presented in the order of a 
values. (If there is an er 
sequence, the KEY condition 
raised.) The associated fi 
opened for DIRECT OUTPUT, a 
entails a larger processing 
for SEQUENTIAL OUTPUT; the 
presented at random. 



is being 
file is opened 
records roust ice 
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will be 
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overhead than 
keys can then be 



Once an INDEXED data set has been 
created, the file that accesses it can be 
opened for SEQUENTIAL INPUT or UPDATE, or 
for DIRECT INPUT cr UPDATE. It cannot be 
opened for OUTPUT. 



SEQUENTIAL ACCESS 

A SEQUENTIAL file that is used to access 
an INDEXED data set may be opened with 
either the INPUT or the UPDATE attribute. 
The data transmission statements need not 
include source keys, nor need the file have 
the KEYED attribute. Sequential access is 
in order of ascending recorded-key values; 
records are retrieved in this crder, and 
not necessarily in the order in which they 
were added to the data set. 

The rules governing the relationship 
between the READ and REWRITE statements for 
a SEQUENTIAL UPDATE file that accesses an 
INDEXED data set are identical to those for 
a CONSECUTIVE data set (described above). 

During sequential access of an INDEXED 
data set, it is possible to reposition the 
data set to a particular record by supply- 
ing a source key in the KEY option of a 
READ statement, and to continue sequential 
reading from that record. (The associated 
file must have the KEYED attribute.) Repo- 
sitioning can occur in either a forward or 
a backward direction. Thus, a READ state- 
ment that includes the KEY option will 
cause the record whose key is supplied to 
be read; a subsequent READ statement 
without the KEY option will cause the rec- 
ord with the next higher recorded key to be 
read. 

Since the GENKEY option is not supported 
in TSS/360, the source key should be the 
same length as the recorded keys. If the 
source key is longer, it is truncated on 
the right. If it is shorter, the source 
key is padded on the right with blanks. 



the INPUT or the UPDATE attribute. All 
data transmission statements must include 
source keys; the DIRECT attribute implies 
the KEYED attribute. 

A DIRECT UPDATE file can be used to re- 
trieve, add, delete, or replace records in 
an INDEXED data set. 



SUMMARY OF R ECORD- OR 1ENTED TRANSMI SSI ON 

The following points cover the salient 
features of record- oriented transmission 2 

1. A SEQUENTIAL file specifies that the 
data set records can be accessed, 
created, or modified, in a particular 
order, that is, from the first record 
of the data set to the last record of 
the data set (or from the last to the 
first if the BACKWARDS attribute has 
been specified). 

2. A DIRECT file specifies that the data 
set records can be accessed, created, 
or modified, in random order. The 
particular record of the data set to 
be operated upon must be identified by 
a key . 



A data set that is 
or modified by a S 
or nay not have re 
does, the keys can 
accessing sequent! 
extracted fron the 
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SEQUENTIAL OUTPUT 
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data set or rlaced 
by the KEY FROM and 

general, the nest 
reate a data set 
d keys is as a 
file. It then can 
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SEQUENTIAL INPUT and SEQUENTIAL UPDATE 
files may be positioned to a particu- 
lar record within the data set by a 
READ operation that specifies the key 
of the desired record, thereafter, 
successive READ statements without the 
KEY option will access the records 
sequentially. This kind of accessing 
may b j used only if the data set has 
INDEXED organization and if the file 
has the KEYED attribute. 

Existing records of a data set in a 
SEQUENTIAL UPDATE file can be rewrit- 
ten, modified, ignored, or deleted. 
The DELETE statement used with this 
type of file specifies that the last 
record read is to be deleted- 1 - Opera- 
tion with a DIRECT UPDATE file, howev- 



DIRECT ACCESS 

A DIRECT file that is used to access an 
INDEXED data set may be opened with either 



*If the DELETE statement is used with a 
sequential file, the data set must have IN- 
DEXED organization. 
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er, can specify which record is to be 
deleted by means of a key; also, rec- 
ords can be added to the data set by 
means of the WRITE statement. An 
existing record in an UPDATE file can 
be replaced through use of a REWRITE 
statement. 

Although the EXCLUSIVE attribute, the 
NOLOCK option, and the UNLOCK option 
are accepted by the compiler, they 
have no meaning in TSS/360. Inter- 
locks are applied automatically 
whenever a file is opened for DIRECT 
access. 

A WRITE statement adds a record to a 
data set, while a REWRITE statement 
replaces a record. Thus, a WRITE 
statement may be used with OUTPUT 
files, and DIRECT UPDATE files, but a 
REWRITE statement may be used with UP- 
DATE files only. Moreover, for DIRECT 
files, a REWRITE statement uses the 
KEY option to identify the existing 
record tc be replaced? a WRITE state- 
ment uses the KEYFROM option, which 
not only specifies where the record is 
to be written in the data set, but 
also specifies an identifying key to 
be recorded in the data set. 



Records of a SEQU 
SEQUENTIAL UPDATE 
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ENTIAL INPUT or 
file can be skipped 
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IGNORE option speci- 

f records to be 

statement in which 

ion appears indicates 
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EXAMPLES OF DECLARATIONS FOR RECORD FILES 

Following are examples of declarations 
of files, including the ENVIRONMENT 
attribute: 

DECLARE INVNTRY UPDATE BUFFERED 
ENVIRONMENT (F(IOO) 
[ INDEXED) ; 

This declaration also specifies only three 
file attributes: UPDATE, BUFFERED, and 



ENVIRONMENT. Implied attributes are FILE, 
RECORD, and SEQUENTIAL (the last two attri- 
butes are implied by BUFFERED) . Scope is 
EXTERNAL, by default. The data set is of 
INDEXED organization, and it contains 
fixed-length records of 100 bytes each. 
Note that although the data set actually 
contains recorded keys, the KExTO option 
cannot be specified in a READ statement, 
since the KEYED attribute has not been 
specified. 

Ncte that for both of the above declara- 
tions, all necessary attributes are either 
stated or implied in the DECLARE statement. 
None of the attributes can be changed in an 
OPEN statement or in a DDEF command. The 
second declaration might have been written: 

DECLARE INVNTRY 

ENVIRONMENT C F ( 100 ) INDEXED ) ; 

With such a declaration, INVNTRY can be 
opened for different purposes. It could, 
for example, be opened as follows: 

OPEN FILE (INVNTRY) 

UPDATE SEQUENTAIAL BUFFERED; 

With this OPEN statement, the file attri- 
butes would be the same as those specified 
Cor implied) in the DECLARE statement in 
the second example above (the number of 
buffers would have to be stated in the 
associated DDEF command). The file might 
be opened in this way r then closed, and 
then later opened with a different set of 
attributes, for example: 

OPEN FILE (INVNTRY) 

INPUT SEQUENTIAL KEYED? 

This OPEN statement allows records tc be 
read with either the KEYTO or the KEYED 
option. Because the file is SEQUENTIAL and 
the data set is INDEXED, the data set is 
INDEXED, the data set may be accessed in a 
purely sequential manner; or, by means of a 
READ statement with a KEY option, it may be 
accessed randomly. A KEY option in a READ 
statement with a file of this description 
causes a specified record to be obtained. 
Subsequent READ statements without a KEY 
option access records sequentially, begin- 
ning with the next record. 
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SECTION 11. 



EDITING AND STRING HANDLING 



The data manipulation performed by the 
aritnmetic, comparison, and bit-string 
operators are extended in PL/I by a variety 
of string-handling and editing features. 
These features are specified by data attri- 
butes, statement options, built-in func- 
tions, and pseudo-variables. 

The following discussions give general 
descriptions of each feature, along with 
illustrative examples. 



in the case of a character-string variable, 
or with zeros, in the case of a bit-string 
variable* Assume SUBJECT still has the 
attributes CHARACTER (10). Then the fol- 
lowing two statements assign equivalent 
values to SUBJECT: 



SUBJECT = •PHYSICS'; 
SUBJECT = •PHYSICSbbb'; 



ED ITING BY ASSI GNMENT 

The most fundamental form of editing 
performed by the assignment statement 
involves converting the data type of the 
value on the right side of the assignment 
symbol to conform to tne attributes of the 
receiving variable. Because the assigned 
value is made to convoriri to the attributes 
of the receiving field, the precision or" 
length of the assigned value may be 
altered. Such alteration can involve the 
addition of digits or characters to and the 
deletion of digits or characters from the 
converted item. The rules for data conver- 
sion are discussed in Part I, Section 4, 
"Expressions and Data Conversion," and in 
Part II, Section 6, "Problem Data 
Conversion . " 



ALTERING THE LENGTH OF STRING DATA 

When a value is assigned to a string 
variable, it is converted, if necessary, to 
the same string type (character or bit) as 
the receiving string and also, if neces- 
sary, is truncated or extended on the right 
to conform to the declared length of the 
receiving string. For example, assume SUB- 
JECT has the attributes CHARACTER CIO), 
indicating a fixed-length character string 
of ten characters. Consider the following 
statement : 



SUBJECT 



1 TRANSFORMATIONS ' ; 



The length of the string on the right is 
fifteen characters; therefore, five charac- 
ters will be truncated from the right end 
of the string when it is assigned to SUB- 
JECT. This is equivalent to executing: 



SUBJECT 



'TRANSFORMA' ; 



If the assigned string is shorter than 
the length declared for the receiving 
string variable, the assigned string is 
extended on the right either with blanks, 



The letter b indicates a blank character. 

Let CODE be a bit-string variable with 
the attributes BIT (10). Then the following 
two statements assign equivalent values to 

CODE: 

CODE = , 110011 , B; 
CODE = 'HOOllOOOO'B; 

Note, however, that the following state- 
ments do not assign equivalent values to 
SUBJECT if it has the attributes CHARACTER 
(10) : 



SUBJECT 
SUBJECT 



" 110011 s B; 
■llOOllOOOO'B; 



When the first statement is executed, the 
tit-string constant on the right is first 
converted to a character string and is then 
extended on the right with blank characters 
rather than zero bits. This statement is 
equivalent to: 

SUBJECT = ■llOOllbbbb' ; 

The second of the two statements 
requires only a conversion from bit-string 
to character-string type and is equivalent 
to: 

SUBJECT = • 1100110000' ; 
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For the TSS/360 compiler the length, in 
characters or tits, of a string variable or 
intermediate string result is limited to 
32,767 a 
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OTHER FORMS OF ASSIGNMENT 

In addition to the assignment statement, 
PL/I provides other ways of assigning 
values to variables. Among these are two 
methods that involve input and output sta- 
tements: one in which actual input and 
output operations are performed, and one in 
which data movement is entirely internal. 



Input and Output Operations 

Although the assignment statement is 
concerned with the transmission of data 
between storage locations internal to a 
computer, input and output operations can 
also be treated as related forms of assign- 
ment in which transmission occurs between 
the internal and external storage facili- 
ties of the computer. 

Record-oriented operations, however, do 
not cause any data conversion of items in a 
logical record when it is transmitted. 
Required editing of the record must be per- 
formed within internal storage either 
before the record is written or after it is 
read. 

Stream-oriented operations, on the other 
hand, do provide a variety of editing func- 
tions that can be applied when data items 
are read or written. These editing func- 
tions are similar to those provided by the 
assignment statement, except that any data 
conversion always involves character type, 
conversion from character type on input, 
and conversion to character type on output. 

The STRING Option in GET and PUT Statements 

The STRING option in GET and PUT state- 
ments allows the statements to be used to 
transmit data between internal storage 
locations rather than between the internal 
and external storage facilities. In both 
GET and PUT statements, the FILE option, 
specified by FILE (file-name), is replaced 
by the STRING option, as shown in the fol- 
lowing formats: 

GET STRING (character-string-variable) 
data- specification; 

PUT STRING (character-string-variable) 
data-specification; 

The GET statement specifies that data items 
to be assigned to variables in the data 
list are tc be obtained from the specified 
character string. The PUT statement speci- 
fies that data items of the data list are 
to be assigned to the specified chjracter- 
string variable. The "data-specification" 
is the same as described for i« put and out- 
put. In general, it takes one of the fol- 
lowing forms: 



DATA [ (data-list) ] 

LIST (data-list) 

EDIT (data-list) (format-list) 



Although the STRING option can be used 
with each of the three modes of stream- 
criented transmission, it is most useful 
with edit-directed transmission, which con- 
siders the input stream to be a continuous 
string of characters. For list-directed 
and data-directed GET statements, individu- 
al items in the character string must be 
separated by commas or blanks; for data- 
directed GET statements, the string must 
also include the transmission- terminating 
semicolon, and each data item must appear 
in the form of an assignment statement. 
Edit-directed transmission provides editing 
facility by means of the format list. 

The STRING option permits data gathering 
cr scattering operations to be performed 
with a single statement, and it allows 
stream-oriented processing of character 
strings that are transmitted by record- 
criented statements. 

Consider the following statement: 

PUT STRING (RECORD) EDIT 

(NAME, PAY**, HOURS*RATE) 
(A(12), A(7), P'$999V.99 i ) ; 



This statement s 
character- string 
assigned to the 
character positi 

RECORD, and that 
of PAY# is to be 
character positi 
of HOURS is then 
value of RATE, a 
edited into* the 
tions, according 
specification. 



pecifies that the 

value of NAME is to be 
first (leftmost) 12 
ons of the string named 
the character-string value 
assigned to the next seven 
ons of RECORD. The value 

to be multiplied by the 
nd the product is to be 
next seven character poci- 
to the picture 



Frequently, it is necessary to read rec- 
ords of different formats, each of which 
gives an indication of its format within 
the record by the value of a data item. 
The STRING option provides an easy way to 
handle such records; for example: 

READ FILE (INPUTR) INTO (TEMP); 
GET STRING (TEMP) EDIT (CODE) (F<1)); 
IF CODE -,= 1 THEN GO TO OTHER_TYPE; 
GET STRING (TEMP) EDIT (X,Y,Z) 
(X(l), 3 F(1Q, **)) ; 

The READ statement reads a record from the 
input file INPUTR. The first GET statement 
uses the STRING option to extract the code 
from the first byte of the record and to 
assign it to CODE. The code is tested to 
determine the format of the record. If the 
code is 1, the second GET statement then 
uses the STRING option to assign the items 
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in the record to X f Y, and Z. Note that the 
second GET statement specifies that the 
first character in the string TEtfP is to be 
ignored (the XC1) format item in the format 
list). Each GET statement with the STRING 
option always specifies that the scanning 
is to begin at the first character of the 
string. Thus, the character that is 
ignored in the second GET statement is the 
same character that is assigned to CODE by 
the first GET statement. 

In a similar way, the PUT statement with 
a STRING option can be used to create a 
record within internal storage. In the 
following example, assume that the file 
CUTPRT is eventually to be printed. 

PUT STRING (RECORD) EDIT 

(NAME, PAY# r HOURS*RATE) 
(X(l), AC12), XC10), A(7), X(10), 
P'$999V.99 a ) ; 

WRITE FILE (OUTPRT) FROM (RECORD); 

The PUT statement specifies, by the X(l) 
spacing format item, that the first 
character assigned to the character-string 
variable is to be a single blank, the ANSI 
carriage-control code that specifies a 
single space before printing. Following 
that, the values of the variables NAME and 
PAY# and of the expression HOURS*RATE are 
assigned. The format list specifies that 
ten blank characters are to be inserted 
between NAME and PAY# and between PAY# and 
the expression value. The WRITE statement 
specifies that record transmission is to be 
used to write the record into the file 
OUTPRT. 



THE PICTURE SPECIFICATION 

Picture specifications extend the edit- 
ing facilities available in PL/I, and pro- 
vide the user with greater control over his 
data formats. A picture specification con- 
sists of a sequence of character codes en- 
closed in apostrophes which is either part 
of the PICTURE attribute, or part of the P 
(picture) format-item: 

DECLARE PRICE PICTURE 8 $Z9V99 ' ; 

PUT FILE(SYSPRINT) EDIT 

('PART NUMBER 1 , PART#) 
(A(12), P«AAA99X'); 

Picture specifications are of two types: 

• numeric character specifications 

• character-string picture specifications 

A numeric character specification in a 
PICTURE attribute indicates that the data 
item represents a numeric quantity, but 
that it is to be stored as a character 



string; it also indicates how the numeric 
value is to be represented in the string. 
A nuireric character, specified in a P for- 
mat item, indicates how a numeric value is, 
or is to be, represented as a character 
string on the external medium. 

A character-string picture specification 
is an alternative weiy of describing a 
fixed-length character string, with the 
additional facility of specifying positions 
in the string that can only contain charac- 
ters from certain subsets of the corrplete 
set of characters available on the IBM 
System/360 Operating System. 

The concepts of the two types of picture 
specifications are described separately 
below, and a detailed description of each 
picture character, together with examples 
of its use, appears In Part II, Section 4, 
"Picture Specification Characters." It is 
sufficient here to note that the presence 
of an A or X picture character defines a 
picture specification as a character-string 
picture specification; otherwise it is a 
numeric character specification. 



Numeric Characte r g^ecJ.f^aJbiQns 

A numeric character specification speci- 
fies that the associated data item has a 
numeric value, but is to be maintained 
j within the computer (or, is represented in 
j the external medium) as a character string. 
j It also specifies the term the character 
j string is to take, and exactly how the num- 
eric value is represented in the string. 
; For example: 

DCL PRICE PICTURE* $29V99 9 ; 

: This specifies that PRICE is to be repre- 
j sented by a character string of length 5. 
| The first character is always $ s the second 
j is a blank or non-zero digit, and the 
I third, fourth, and fifth characters are 
i digits. The numeric value is the four 
' characters that can represent digits, 
-. regarded as FIXED DECIMAL (4,2), and is 

always positive. 1.3. 2S Is represented as 

'$1325 ' and .95 as , $b095'. 

The numeric character specification has 
; two major uses; 

• The first use is for data items that 

will be concerned with Input/ output 
» operations, bur can be used anywhere in 
; a program where numeric data can occur. 
However, on IBM System/360 Time Sharing 
System, most numeric operations on pic- 
j tured data are considerably less effi- 
cient than the same operations on coded 
numeric data. 

• The second use stems from the fact that 

a pictured dat,i i>ein effectively has 
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two values. When the it tin is used in a 
numeric context, the nuint*ric value it; 
obtained from or stored into the 
character striny r by the conversion 
process defined by the picture specifi- 
cation; when the item is used in a 
character context, the actual character 
string that represents the value is 
used. For example: 



DCL COUNT PICTURE 1 999* 

STRING CHAR (3) ; 
COUNT = COUNT 4-1; 
ST KING = COUNT; 



INITIAL(O) , 



The initial reprenentation of COUNT is 
•000*. In the first assignment state- 
ment this is converted to FIXED DECIMAL 
(3,0); the addition is performed; and 
the result is converted back to the 
pictured form • 001'. In the second 
assignment statement the value ot 
strinq is set to '001'. 



represented by a fixed- length character 
string of length n, each character of which 
is a digit (zero through nine). The- numer- 
ic value is the value of the digits as an 
unsigned deeimai number (i.e., FIXED DECI- 
MAL (n,0>). For example: 

■DCL DIGIT PICTURE' 9 • , 

COUNT PICTURE'999' , 
XYZ PICTURE ' (10) 9 f ; 



an alternative way of 
character i 9' ten 



The last line shows 
writing the picture 

times. 

Example of use; 



DCL 1 CARD_ IMAGE, 

2 DATA CHAR (7 2) , 

2 IDENTIFICATION CHAR(3), 

2 SEQUENCE PIC 99999'; 



Note that "character context" includes 
defining. A numeric-character data 
item may be defined on a character 
string and vice versa . 

When a character -string value is 
assigned to a numeric character data 
item (whether by direct assignment, or 
as the result of s tream-or ient ed I/O), 
the source must contain a constant that 
is valid according to the rules tor 
constants in PL/1 source programs,. The 
value of this constant is then con- 
verted and edited to the picture 
specification . 

The following example will therefore 
result in a conversion error: 

DCL A PICTURE •$$$9V.99 i ; 
A = '$17.95'; 

The currency symbol makes the 
character-string constant invalid for 
conversion to the arithmetic value of 
the numeric character variable, even 
though its character-string value con- 
tains a currency symbol. 

Correct examples are: 



SEQUENCE = SEQUENCE ♦ 1; 

WRITE FILE(OUTPUT) FROM ( CAR D_ IMAGE ) ; 

Note that the definition of *9" in a 
character-string picture allows the corres- 
ponding character to be either a blank or a 
digit . 

The Z and » Picture Characters 

It if; often preferable to replace lead- 
ing zeros in numbers by blanks I In picture 
specif icat ions, this is accomplished by 
using the Z picture character. A picture 
specification containing only Z's and 9's 
has one or more Z's optionally followed by 
one or more 9 f s. The representation of 
numeric data is as for the • 9' picture spe- 
cification, except that if the digit to be 
held would otherwise be zero and if all 
digit positions to the left would also be 
zero, then the character string will con- 
fain a blank in this position. Example: 

DCL PAGE _NUMUER PICTURE * ZZ9 f ; 

197 is held as , 197 , l 69 as , b69 , # 5 as 
'bb5*, and zero as ' bbQ'. With a picture 
specification of all Z's, a value of zero 
is held as an all-blank string. 



A = '17. 95'; 
A = 17.95; 

either of which would result in A hav- 
ing the character-string value b$l7.95. 

The '9* Picture Character in Numeric 
Character Specifications 

The picture character f 9' is the simp- 
lest form of numeric character specifica- 
tion. A string of n, "9* picture charac- 
ters specifies that the item is to be 



The asterisk picture character has the 
same effect as the ' Z f , except that an ' *' 
is held in the string instead of a blank. 
This can be used, for example, when print- 
ing checks, when it is desired not to leave 
blank spaces within fields. For example: 

DCL CREDIT PICTURE '$**9.99'; 

(The $ and . picture characters are 
described below.) A value of 95 is held as 
■$**0.9V; a value of 12350 is held as 

' $1 23. 50' . 
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The V Picture Character 

Up to now, numeric character specif ica- 
tions have only represented non- negative 
integer values. The V picture character 
indicates the position of an assumed deci- 
mal point within the character string. For 
example: 

DCL VALUE PICTURE t Z9V999 i ; 

The string • 12345* represents the numeric 
value 12.345. Note that the V does not 
specify a character position in the 
character- string representation; on assign- 
ment to the data item, a decimal point is 
not included in the character .string. 



The Insertion Picture Characters: 



B 



A decimal point picture character (»> 
can appear in a numeric picture .specifica- 
tion. It merely indicates that a decimal 
point is to be included in the character 
representation of the value. Therefore, 
tne decimal point is a part of its 
character-string value. The decimal point 
picture character does not cause decimal 
point alignment during assignment; it is 
not a part of the variable's arithmetic 
value. Only tht-* V picture character causes 
alignment of decimal points. For example: 

DECLARE SUM PICTURE " 999V. 99'; 

SUM is a numeric character variable repre- 
senting numbers of five digits with a deci- 
mal point assumed between the third and 
fourth digits. The actual point specified 
by the decimal point insertion character is 
not a part of the arithmetic value; it is, 
however, part of its character-string 
value. (The decimal point picture charac- 
ter can appear on either side of the char- 
acter V. Gee Part II, Section 4, "Picture 
Specification Characters,") The following 
two statements assign the same character 
string to SUM: 

SUM = 123; 
SUM = 123.00; 

In the first statement, two zero digits are 
added to the right of the digits 123. 

Note the effect of the following 
declaration: 

DECLARE RATE PICTURE ' 9V99.99'; 

Let RATE be used as follows: 

RATE = 7.62; 

When this statement is executed, decimal 
point alignment occurs on the character V 



and not on the decimal point picture char- 
acter that appears in the picture specifi- 
cation for RATE. If RATE were printed, it 
would appear as "762. 00*, but its arithme- 
tic value would be 7.6200. 



Unlike the V picture character, which 
can appear only once in a picture specifi- 
cation, the decimal point picture character 
can appear more than once; this allows 
digit groups within the numeric character 
data item t o be separated by points, as is 
common in Dewey decimal notation and in the 
numeric notations of some European 
countries. 

Because a decimal point picture charac- 
ter causes a period character to be 
inserted into the character-string value of 
a numeric character data item, it is called 
an insertion character. PL/I provides 
three other insertion characters: comma 
(,), slash (/), and blank CB), which are 
used in the? same way as the decimal point 
picture character except that a comma, 
slash, or blank is inserted into the char- 
acter string. Consider these statements: 

DECLARE RESULT PICTURE • 9 . 999 . 999 , V99 ' ; 
RESULT = 1234567; 

The character-string value of RESULT would 
be '1.234.567, 00* . Note that decimal point 
alignment occurs before the 'two rightmost 
digit positions, as specified by the V pic- 
ture character. If RESULT were assigned to 
a coded arithmetic field, the value of the 
data converted to arithmetic would be 
1234567.00. 



The $ Picture Character 

The $ picture character controls the 
appearance of the currency symbol ($) in 
specified positions of numeric character 
data items. For example, a dollar sign can 
be appended to the left of a numeric char- 
acter item, as indicated in the following 
statements : 

DECLARE PRICE PICTURE f $99V.99 s ; 
PRICE = 12.45; 

The character-string value of PRICE is 
equivalent to the character-string constant 
•$12.45 f . Its arithmetic value, however, 
is 12.45. 



Sign Specification in Numeric Character 
Specif icat ions 

There are several ways in which signed 
information can be held in a numeric char- 
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acter data item. The simplest of these is 
the S character specification. This speci- 
fies a character in the character-string 
representation that contains •♦■ if the 
value is positive or zero, and •-* if the 
value is negative. It must occur either to 
the right or to the left of all digit posi- 
tions. For examples 

DCL ROOT PICTURE f S999 s ; 

50 is held as f *050 f , zero as f 4»000 f , and 
-243 as •-2H3". Similarly the •♦• picture 
character specifies a corresponding charac- 
ter position containing • ♦ * for positive or 
zero, and blank for negative values i the 
* - s picture character specifies a corres- 
ponding character position containing blank 
for positive or zero, and •- " for negative 
values. 

Overpunched Sign-Specification Characters: 
T, I, and R 

An alternative way of representing 
signed values, which does not require an 
additional character in the string, is by 
an overpunched sign specification. This 
representation arose from the custom of 
indicating signs in numeric data held on 
punched cards, by superimposing a 12-punch 
Cto represent +) or an 11 -punch (to repre- 
sent -) on top of a column containing a 
digit (usually the last one in a field) . 
The resulting card code is, in most cases, 
the same as that for an alphabetic charac- 
ter, e.g., 12-punch superimposed on 1 
through 9 gives A through I, It-punch 
superimposed on 1 through 9 gives J through 
R. The 12-0 and 11-0 combinations are not 
characters in the PL/I set but are within 
the set of characters accepted by the IBM 
System/360 Time Sharing System implementa- 
tions for character data. 

The T picture character specifies a 
character in the character-string represen- 
tation that holds a digit and sign, in the 
representation described above, i.e., 12- 
punch superimposed on 1 through 9 (A 
through I) for positive or zero, 11-punch 
superimposed on 1 through 9 (J through R) 
for negative. It can appear anywhere a •9' 
picture specification character could have 
occurred. For example: 

DCL CREDIT PICTURE , ZZV9T I ; 

The character-string representati >n of 
CREDIT is 4 characters. +21.05 is held as 
B 210E*. -0.07 is held as *bb0P - . 

The I picture character specifies a 
character position that holds the represen- 
tation of a digit overpunched with a 12- 
punch if the value is positive or zero, or 
a digit without overpunch, if the value is 
negative. 



The R picture character specifies a 
character position that holds the represen- 
tation of a digit overpunched with an 11- 
punch if the value is negative,, or a digit 
without overpunch, if the value is posi- 
tive* For example: 

GET EDIT (X) tP , R99 t )? 

sets X to C+)132 on finding , 132 i in the 
next 3 positions of the input stream, but 
to -132 on finding S J32«. 

Other Num eric -Character Facilities 

Further details of usage of the above 
picture specification characters, together 
with details of picture specification char- 
acters for floating signs and currency sym- 
bols , floating point values, and sterling 
values, appear in Part u. Section 4, "Pic- 
ture Specification Characters." 

The full list of numeric-character- 
specification characters is 9,V f 2 f * f Y, 
(.), (,),1,B, S, ♦,-, $ f CR,DB,T f I,R,K,E,F,8 f 7,6 
P,H f G,,G f H, and M f of which all except K,¥, 
F,G, and M specify the occurrence of a 
character in the character-string 
repr es ent at ion - 

C har acter- st ring Picture Specifications 

A character-string picture specification 
is an alternative way of describing a 
fixed-length character string, with the 
additional facility of specifying positions 
in the string that only contain characters 
from certain subsets of the complete set of 
characters available on the IBM System/360 
Time Sharing System. 

A character-string picture specification 
is recognized by the occurrence of an A or 
X picture character. The only valid char- 
acters in a character-string picture speci- 
fication are A, X r and 9. Each of these 
specifies -the presence, in the character 
string, of one character position that can 
contain the following: 

X Any character recognized by the 

particular implementation (for the 
IBM System/360 Time Sharing System, 
any of the 256 bit combinations 
that can occur in the 8-bit byte). 

A Any alphabetic character, or blank, 

9 Any digit, or blank. Note the dif- 
ference from the 9 picture charac- 
ter in numeric character 
specifications. 

When a character-string value is assigned, 
or transferred, to a pictured character- 
string data item, the particular character 
in each position is checked for validity. 
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as specified by the corresponding picture 
specification character* If the character 
is invalid, the CONVERSION condition is 

raised. For example : 

DECLARE PART# PICTURE i AAA99X"; 

The following values are valid for assign- 
ment to PART#. 

f ABC12M' 
•bbb09/ f 
•XYZM.3 1 

The following values are not (the invalid 
characters are underscored) % 

'ABl^M* 
•ABCl/2 f 
1 Mb#A5 ; ' 



^STRING, a minor structure of bit-strings. 
By default, the elements of PERSONNEL_RE- 
CORD have the UNALIGNED attribute. Conse- 
quently, OODE_STRING is mapped with eight 

elements per byte, that is, in the same way 

as a bit-string of length 25. 

Each of the first two bits of the string 
represents only two alternatives: MALE or 
tMALE and SECRETARIAL or 1 SECRETARIAL. The 
other categories Cat level 3) list several 
alternatives each. (Note that the level 
number 4 and the attributes BIT CD are fac- 
tored for each category. ) 

The following portion of a program might 
be used with PERSONNEL^ RECORDS 

INREC: READ FILE C PERSONNEL) 

INTO CPERSONNELJRECORD) ; 



BIT-STRING HANDLING 

The following examples illustrate some 
of the facilities of PL/I that can be used 
in bit-string manipulations. 

DECLARE 1 PERSONNEL_RECORD, 
2 NAME, 

3 LAST CHARACTER C 15), 
3 FIRST CHARACTER CIO), 
3 MIDDLE CHARACTER CI), 
2 CODE_STRING, 
3 MALE BITC1), 
3 SECRETARIAL BITC1), 
3 AGE, 

U CUNDER_20, 

TWENTYJTO_30, 
OVER__30) BIT CD, 
3 HEIGHT, 
4 COVER_6 r 

FIVE_SIX_TO_6 f 
UNDER_5_6> BIT CI), 
3 WEIGHT, 

4 COVER_180, 

ON E_TEN_TO_l 8 , 
UNDERJL10) BITC1), 
3 EYES, 
4 CBLUE, 
BROWN, 
HAZEL, 
GREY, 

OTHER) BIT CD, 
3 HAIR, 

4 C BROWN, 
BLACK, 
BLOND, 
RED, 
GREY, 

BALD) BITC1), 
3 EDUCATION, 
4 C COLLEGE, 

HIGH_SCHOOL, 
GRAMMARSCHOOL) BIT CD? 

This structure contains NAME, a minor 
structure of character-strings, and CODE- 



IF CtMALE I SECRETARIAL 


£ 


UNDER 20 


£ 


UNDER 5 6 


£ 


UNDER 110 


& 


BLUE 


£ 


CHAIR . BROWN 1 BLOND) 


£ 


HIGEMSCHOOL) 


I 


CMALE £ -J SECRETARIAL 


£ 


OVER 30 


£ 


OVER 6 


£ 


OVER 18 


4 


EYES, GREY 


£ 


BALD 


£ 


COLLEGE) 



THEN PUT LIST CNAME) ; 

GO TO INREC; 

Another way to program the same informa- 
tion retrieval operation, as shown in the 
following coding, would result in consi- 
derably shorter execution time: 

DECLARE PERS_STRING BIT C 25) DEFINED 

CQDE_3TRING; 

IF PERSJSTRING 

= "0110000100110000100000010*8 

THEE GO TO OUTP; 

IF PERS_STRING , 

= 'OIIOOOOIOQUOOOOOOIOOOOIO^ 

THEN GO TO OUTP; 

IF PERS_STR1MG 

= f 1000110010000010000001100 f B 

THEN GO TO OUTP; 

GO TO INREC; 

OUTP: PUT LIST CNAME); 

GO TO INREC; 

In this example, the bit string PERS___STRING 
is defined on the minor structure 
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CODE__STRING. Bit-string constants are con- variations are specified in the first 

structed to represent the values of the example by CHAIR. BROWN | BLOND) . 
information being sought. The bit string 
then is compared, in turn, with each of the 

bit-string constants. Note that the first Note that the second method of testing 

and second constants are identical except PERSONNEL^ RECORD could not be used if the 

that the first tests for brown hair and the structure were ALIGNED Cthe base identifier 

second tests for blond hair. These two for overlay defining must be UNALIGNED) . 
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The first method, if it were used r would be 
more efficient with an ALIGNED structure. 

The tests might also be made with a 
series of IF statements, either nested or 
unnested, in which each tit would be tested 
with a single IF statement. It would 
require a greater amount of coding, but it 
would be faster at execution time than an 
IF statement containing many bit-string 
operators . 



CHARACTER-STRING AND BIT- STRING BUILT-IN 
FUNCTIONS 

PL/I provides a number of built-in func- 
tions, some of which also can be used as 
pseudo-variables, to add power to the 
string-handling facilities of the language. 
Following are brief descriptions of these 
functions (more detailed descriptions 
appear in Part II, Section 1 § "Built-in 
Functions and Pseudo-Variables*) . 

The BIT built-in function specifies that 
a data item is to be converted to a bit 
string. The built-in function allows a 
user to specify the length of the converted 
string, overriding the length that would 
result from the standard rules of data 
conversion . 

The CHAR built-in function is exactly 
the same as the BIT built-in function, 
except that the conversion is to a charac- 
ter string of a specified length. 

The SUBSTR built-in function, which can 
also serve as a pseudo-variable in a 
receiving field, allows a specific sub- 
string to be extracted from (or assigned 
to, in the case of a pseudo-variable) a 
specified string value. 

The INDEX built-in function allows a 
string, eitner a character string or a bit 
string, to be searched for the first occur- 
rence of a specified substring, which can 
tie a single character or bit. The value 
returned is the location of the first char- 
acter or bit of the substring, relative to 
the beginning of the string. The value is 
expressed as a binary integer. If the sub- 



string dees not occur in the specified 
string, the value returned is zero. 



The LENGTH built-in function gives the 
current length of a character string or bit 
string. It is particularly useful with 
strings that have the VARYING attribute. 

The HIGH built-in function provides a 
string of a specified length that consists 
of repeated occurrences of the highest 
character in the collating sequence. For 
System/360 implementations, the character 
is hexadecimal FF. 

The LOW built-in function provides a 
string of a specified length that consists 
of repeated occurrences of the lowest char- 
acter in the collating sequence. For 
System/360 implementations, the character 
is hexadecimal 00. 

The REPEAT built-in function permits a 
string to be formed from repeated occur- 
rences of a specified substring. It is 
used to create string patterns. 

The STRING built-in function which can 
also be used as a pseudo-variable, conca- 
tenates all the elements in an aggregate 
variable into a single string element. 

The BOOL built-in function allows up to 
16 different Boolean operations to be ap- 
plied to two specified bit strings. 

The UNSPEC built-in function, which can 
also be used as a pseudo-variable, speci- 
fies that the internal coded representation 
of a value is to be regarded as a bit 
string with no conversion. 

The TRANSIATE built-in function trans- 
lates a specified string according to a 
translation table defined by two other 
strings. 

The VERIFY built-in function verifies 
that each character or bit in a given 
source string is represented in a given 
verification string; in other words, it 
tests the validity of each character or bit 
according to user-specified criteria. 
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SECTION 12: SUBROUTINES AND FUNCTIONS 



ARGUMENTS AND PARAMETERS 

Data can be made known in an invoked 
procedure by extending the scope of the 
names identifying that data to include the 
invoked procedure. This extension of scope 
is accomplished by nesting procedures or by 
specifying the EXTERNAL attribute for the 
names. 



OUTSUB ; PROCEDURE (A, B) ; 

DFCLARE A CHARACTER (20), 

B BIT (5) ; 



PUT LIST <A f B); 



There is yet another way in which data 
can be made known in an invoked procedure, 
and that is to specify the names as argu- 
ments in a list in the invoking statement. 
Each argument in the list is an expression, 
a file name, a statement label constant or 
variable, or an entry name that is to be 
passed to the invoked procedure. 



Since arguments are passed to it, the 
invoked procedure must have some way of 
accepting them. This is done by the expli- 
cit declaration of one or more pa rameters 
in a list in the PROCEDURE or ENTRY state- 
ment that is the entry point at which the 
procedure is invoked. A parameter is a 
name used within the invoked procedure to 
represent another name (cr expression) that 
is passed to the procedure as an argument. 
Each parameter in the parameter list of the 
invoked procedure has a corresponding argu- 
ment in the argument list of the invoking 
statement. This correspondence is taken 
from left-to-right; the first argument 
corresponds to the first parameter, the 
second argument corresponds to the second 
parameter, and so forth. In general, any 
reference to a parameter within the invoked 
procedure is treated as a reference to the 
corresponding argument. The number of 
arguments and parameters must be the same. 
The maximum number of parameters permitted 
at any entry point is 64. 

The example oelow illustrates how param- 
eters and arguments may be used: 



PRMAIN: PROCEDURE; 

DECLARE NAME CHARACTER (20), 
ITEM BIT (5) ; 



CALL OUTSUB (NAME, ITEM); 



END PRMAIN; 



END OUTSUB; 

In procedure PRMAIN, NAME is declared as 
a character string, and ITEM as a bit 
string. The CALL statement in PRMAIN 
invokes the procedure called OUTSUB, and 
the parenthesized list included in this 
procedure reference contains the two argu- 
ments being passed to OUTSUB. The PROCE- 
DURE statement defining OUTSUB declares two 
parameters, A and B. When OUTSUB is 
invoked, NAME is associated with A and ITEM 
is associated with B. Each reference to A 
in OUTSUB is treated as a reference to NAME 
and each reference to B is treated as a 
reference to ITEM. Therefore, the PUT LIST 
(A,B) statement causes the values of NAME 
and ITEM to be written into the standard 
system output file, SYSPRINT. 

Note that the passing of arguments usu- 
ally involves the passing of names and not 
merely the values represented by these 
names. (In general, the name that is 
passed is usually the address of the value 
or an address that can be used to retrieve 
the value.) As a result, storage allocated 
for a variable before it is passed as an 
argument is not duplicated when the proce- 
dure is invoked. Any change of value spec- 
ified for a parameter actually is a change 
in the value of the argument. Such changes 
are in effect when control is returned to 
the invoking block. 

A parameter can be thought of as 
indirectly representing the value that is 
directly represented by an argument. Thus, 
since both the argument and the parameter 
represent the same value, the attributes of 
a parameter and its corresponding argument 
rrust agree. For example, an obvious error 
exists if a parameter has the attribute 
FILE and its corresponding argument has the 
attribute FLOAT. However, there are cases 
in which such an error may not be so 
obvious, for example, when an argument is a 
constant. Certain inconsistencies between 
the attributes of an argument and its asso- 
ciated parameter can be resolved by speci- 
fying, in an invoking procedure, the ENTRY 
attribute for an entry name to be invoked. 
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The ENTRY attribute specification provides 
the facility to specify that the compiler 

is to generate coding to convert one or 
more arguments to conform with the attri- 
butes of the associated parameters. This 

topic is discussed later in this chapter in 
the sections "The ENTRY Attribute" and 
"Dummy Arguments," 

A name is explicitly declared to be a 
parameter by its appearance in the parame- 
ter list of a PROCEDURE or ENTRY statement. 
However, its attributes, unless defaults 
a PPly# must be explicitly stated within 
that procedure in a DECLARE statement. 

Parameters, therefore, provide the means 
for generalizing procedures so that data 
whose names may not be known within such 
procedures can, nevertheless, be operated 
upon. There are two types of generalized 
procedures that can be written in PL/I: 
subroutine procedures (call€*d simply, sub- 
routines ) and function procedures 
C functions) . 



SUBROUTINES 

A subroutine is a procedure that is 
invoked by a CALL statement and usually 
requires arguments to be passed to it. It 
can be either an external or internal pro- 
cedure. A reference to such a procedure is 
known as a subroutine reference . The gen- 
eral format of a subroutine reference is as 
follows: 

CALL entry-name I (argument I , argument ]...)] ; 



these is considered to be a normal 

return. 

2. Control reaches a RETURN statement in 
the subroutine. This causes the same 
normal return caused by the END 

statement. 

3. Control reaches a GO TO statement that 
transfers control out of the subrou- 
tine. (This is not permitted if the 
subroutine is invoked by the CALL 
option.) The GO TO statement may 
specify a label in a containing block 
(the label must be known within the 
subroutine) , or it may specify a pa- 
rameter that has been associated with 
a label argument passed to the subrou- 
tine. Although this is considered to 
be normal termination of the subrou- 
tine, it is not normal return of con- 
trol, as effected by an END or RETURN 
statement . 

A STOP or EXIT statement encountered in a 
subroutine abnormally terminates execution 
of that subroutine and of the entire pro- 
gram associated with the procedure that 
invoked it. 

The following example illustrates how a 
subroutine interacts with the procedure 
that invokes it: 

A; PROCEDURE; 

DECLARE RATE FLOAT (10), TIME FLOAT (5), 
DISTANCE FLOAT (15), MASTER FILE; 



Note that a subroutine can also be invoked 
through the CALL option of an INITIAL 
attribute specification. 

Whenever a subroutine is invoked, the 
arguments of the invoking statement are 
associated with the parameters of the entry 
point, and control is then passed to that 
entry point. The subroutine is thus acti- 
vated, and execution begins. 

Upon termination of a subroutine, con- 
trol normally is returned to the invoking 
block. A subroutine can be terminated 
normally in any of the following ways: 



CALL READCM (RATE, TIME, DISTANCE, 
MASTER) ; 



END A; 

READCM: PROCEDURE (W,X,Y,Z); 

DECLARE W FLOAT (10), X FLOAT(S), 



Y FLOAT (15) , Z FILE; 



GET FILE (Z) LIST (W,X,Y); 



1. Control reaches the final END state- 
ment of the subroutine. Execution of 
this statement causes control to be 
returned to the first executable 
statement logically following the 
statement that originally invoked the 
subroutine. There is an exception, 
however: return of control from a 
subroutine invoked by the CALL option 
is to the statement containing the 
CALL option at the point immediately 
following that option. Either of 



Y = W*X; 

IF Y > THEN RETURN; 

ELSE PUT LIST ('ERROR READCM'); 
END READCM; 

The arguments RATE, TIME, DISTANCE, and 
MASTER are passed to the parameters W t X, 
Y, and Z. Consequently, in the subroutine, 
a reference to W is the same as a reference 
to RATE, X the s-nip as TIME, Y the same as 
DISTANCE, and Z the same as MASTER. 
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FUNCTIONS 

A function is a procedure that always 
returns a single value to the point of 
invocation. It usually requires arguments 
to be passed to it when it is; invoked, anci 
is invoked by the appearance of the func- 
tion name (and associated arguments) in an 
expression. Such an appearance is called a 
| function reference . Like a subroutine, a 
function can operate upon the arguments 
passed to it and upon other known data. 
But unlike a subroutine, a function is 
written to compute a single value which is 
returned, with control, to the point of 
invocation, the function reference. Thi,s 
single value can be of arithmetic, string 
(including picture data), locator, or area 
type. The maximum number of different data 
types or precisions returned by one func- 
tion may not exceed 256. An example of a 
function reference is contained in the fol- 
lowing procedure: 

MAINP: PROCEDURE; 



GET LIST (A, B, C, Y) ; 



X = Y**3*SPROD(A, B,C) ; 



END MAINP; 

In the above procedure, the assignment 
statement 

X = Y**3+SPROD(A r B,C) ; 

contains a reference to a function called 
SPROD. The parenthesized list following 
the function name contains the arguments 
that are being passed to SPROD. Assume 
that SPROD has been defined as follows: 

SPROD: PROCEDURE (U,V,W); 



IF U > V ♦ W 

THEN RETURN (0); 
ELSE RETURN <U*V*W) ; 



applied to each argument and parameter. 
(The default precision is that defined for 
System/360 implementations „ ) Hence, the 
attributes are consistent, and the associa- 
tion of the arguments with the parameters 
produces no error. 



During the execution of SPROD, the IF 
statement is encountered and a test is 
made. If U is greater than V ♦ W, the 
statement associated with the THEN clause 
is executed; otherwise, the statement asso- 
ciated with the ELSE clause is executed. 
In either case, the executed statement is a 
RETURN statement. 

The RETURN statement is the usual way by 
which a function is terminated and control 
is returned to the invoking procedure. Its 
use in a function differs somewhat from its 
use in a subroutine; in a function, not 
only does it return control but it also 
returns a value to the point of invocation. 
The general form of the RETURN statement, 
when it is used in a function, is as 
follows : 

RETURN (element-expression) ; 

The expression must be present and must 
represent a single value; i.e., it cannot 
be an <jrray or structure expression. It is 
this value that is returned to the invoking 
procedure at the point of invocation. 
Thus, for the above example/ SPROD returns 
either or the value represented by U*V*W, 
along with control to the invoking expres- 
sion in MAINP. The returned value then 
effectively replaces the function 
reference, and evaluation of the invoking 
expression continues. * 

A function can also be terminated by 
execution of a GO TO statement. If this 
method is used, evaluation of the expres- 
sion that invoked the function will not be 
completed, and control will go to the des- 
ignated statement. As in a subroutine, the 
transfer point, specified in a GO TO state- 
ment may be a parameter that has been asso- 
ciated with a label argument. For example, 
assume that MAINP and SPROD have been 
defined as follows: 

MAINP: PROCEDURE; 



END SPROD; 

When SPROD is invoked by MAINP, the 
arguments A, B, and C are associated with 
the parameters U, V, and W, respectively. 
Since attributes have not been explicitly 
declared for the arguments and parameters, 
default attributes of FLOAT DECIMAL (6) are 



GET LIST (A.B.CY); 

X F Y**3*SPROD(A, B t C t LABI) ; 



LABI: CALL ERRT; 
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END MAINP; 

SPROD: PROCEDURE (U,V,W, Z) ; 
DECLARE Z LABEL? 



IF U > V + W 

THEN GO TO Z; 

ELSE RETURN (U*V*W) ; 



END SPROD; 

In MAINP, LABI is explicitly declared to 
be a statement label constant, by its 
appearance as a label for the CALL ERRT 
statement. When SPROD is invoked, LABI is 
associated with parameter Z. Since the 
attributes of A must agree with those of 
LABl r Z is declared to have the LABEL 
attribute. When the IF statement in SPROD 
is executed, a test is made- If U is 
greater than V 4- w f the THEN clause is 
executed, control returns to MAINP at the 
statement labeled LABI, and evaluation of 
the expression that invoked SPROD is dis- 
continued. If U is not greater than V + W, 
the ELSE clause is executed and a return to 
MAINP is -made in the normal fashion. Addi- 
tional information about the use of label 
arguments and label parameters is contained 
in the section "Relationship of Arguments 
and Parameters* in this section* 

Note : In some instances , a function may be 
so defined that it does not require argu- 
ments. In such cases, the appearance of 
the function name within an expression will 
be recognized as a function reference only 
if the function name has been explicitly or 
contextually declared to be an entry name. 
See "The ENTRY Attribute* in this section 
for additional information- 

Attributes of Returned Values 

The attributes of the value returned by 
a function may be declared in two ways: 

1. They may be declared by default 
according to the first letter of the 
function name. 

2. They may be explicitly declared in the 
RETURNS option of the PROCEDURE (or 
ENTRY) statement for the function. 

The value of the expression in the RETURN 
statement is converted within the function, 
whenever necessary, to conform to the 
attributes specified by one of the two 
methods above. 

Attributes specified in ENTRY statements 
can be different from those specified in 
the encompassing PROCEDURE statement. 



In the previous examples of MAINP and 
SPROD, the PROCEDURE statement of SPROD 
contains no attributes declared for the 
value it returns. Thus, these attributes 
must be determined from the first letter of 
its name, S. The attributes of the 
returned value are therefore FLOAT and 
DECIMAL. Since these are the attributes 
that the returned value is expected to 
have, no conflict exists. 

Note : Unless the invoking procedure pro- 
vides the compiler with information to the 
contrary, the attributes of 'the value 
returned by a function to the invoking pro- 
cedure are always determined from the first 
letter of the function name. 

The RETURNS Option : The way in which 
attributes can be declared for the returned 
value in the PROCEDURE or ENTRY statement 
is illustrated in the following example. 
Assume that the PROCroURE statement for 
SPROD has been specified as follows: 

SPROD: PROCEDURE (U f V,W,Z) RETURNS 
(FIXED BINARY); 

With this declaration, the value returned 
by SPROD will have the attributes FIXED and 
BINARY. However, since these attributes 
differ from those that would be determined 
from the first letter of the function name, 
this difference must be stated in the 
invoking procedure to avoid a possible 
error. The PL/1 user communicates this 
information to the compiler with the 
RETURNS attribute specified in a DECLARE 
statement in the invoking procedure. 



The RETURNS Attribute: 



The RETURNS attri- 



bute is specified in a DECLARE statement 
for an entry name. it specifies the attri- 
1 bute of the value returned by that func- 
tion. It further specifies, by implica- 
tion, the ENTRY attribute for the name; 
consequently, it is an entry name attribute 
specification . Unless default attributes 
for the entry name apply, any invocation of 
a function must appear within the scope of 
a RETURNS attribute declaration for the 
entry name. For an internal function, the 
R£I*l;RNS attribute can be specified only in 
a DECLARE statement that is internal to the 
same block as the function procedure. 

The general format of the RETURNS attri- 
bute is: 

RETURNS (attribute-list) 

A RETURNS attribute specifies that within 
the invoking procedure the value returned 
from the named entry point is to be treated 
as though it had the attributes given in 
the attribute list. The word treated is 
used because no conversion is performed in 
an invoking block upon any value returned 
to it. Therefore, if the" attributes of the 
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returned value do not agree with those in 
the attribute list of the RETURNS attri- 
bute, an error will probably result* 

In, order to specify to the compiler that 
coding for MAINP is to handle the FIXED 
BINARY value being returned by SPROD, this 
declaration must be given within MAINP: 

DECLARE SPROD RETURNS C FIXED BINARY) ; 

Note what is implied in the above dis- 
cussion- During compilation of the invok- 
ing block , there is no way for the compiler 
to check a function procedure to determine 
the attributes of the value it returns. In 
the absence of explicit information in a 
RETURNS attribute specification, the corn- 
pi ler can only assume that the attributes 
will be consistent with the attributes 
implied by the first letter of the function 
name. This is true even if the function 
procedure is contained in the invoking pro- 
cedure. If the returned value does not 
have the attributes that the invoking pro- 
cedure is prepared to receive, no conver- - 
si on can be performed. The RETURNS attri- 
bute must be declared for a function that 
returns any value. 



But since built-in function names are 
PL/I keywords, they are not reserved? the 
same identifiers can be used as user- 
defined names* Consequently* ambiguity 
might occur if a built-in function 
reference were to be used in a block that 
is contained in another block in which the 
same identifier is declared for some other 
purpose* To avoid this ambiguity, the 
BUILT1N attribute can be declared for a 
built-in function name in any block that 
has inherited, from a containing block, 
some other declaration of the identifier. 
Consider the following example. 

A: PROCEDURE; 



B: BEGIN; 

DECLARE SQRT FLOAT BINARY; 



C: BEGIN; 

DECLARE SQRT BUILT IN; 



END C; 



Built-in Functions 



Similar to function procedures that a 
user can define for himself is a comprehen- 
sive set of pre-defined functions called 
]?l 3 li. ! ■ :: ll.IL. functions , 

The set of built-in functions is an 
intrinsic part of PL/I. It includes not 
only the commonly used arithmetic functions 
but also other necessary or useful func- 
tions related to language facilities, such 
as functions for manipulating strings and 
arrays. 

Built-in functions are invoked in the 
same way that user-defined functions are 
invoked. However, many built-in functions 
can return array or structure values, 
whereas a user-defined function can return 
only an element value. 

Note : Some built-in functions may actually 
be compiled as in-line code rather than as 
procedure invocations. All are referred to 
in a PL/ I source program, however, by func- 
tion references, whether or not they result 
in an actual procedure invocation- 

Neither the ENTRY attribute nor the 
RETURNS attribute can be specified for am 
built-in function name. The use of the 

name in a function reference is recognized 
without need for any further identifica- 
tion; attributes of values returned by 
built-in functions are known by the 

compiler. 



END E; 



END A; 

Assume that in external procedure A, 
SQRT is neither explicitly nor contextually 
declared for some other use* Consequently, 
any reference to SQRT would refer to the 
built-in function of that name. In B # 
however, SQRT is declared to be a floating- 
point binary variable, and it cannot be 
used in any other way. Finally, in C, SQRT 
is declared with the BUILTIN attribute so 
that any reference to SQRT will be recog- 
nized as a reference to the built-in func- 
tion and not co the floating-point binary 
variable declared in B. 

Note that a variable having the same 
identifier as a built-in function can be 
contextually declared by its appearance on 
the left-hand side of an assignment symbol 
Cin an assignment statement, a DO state- 
ment, or a repetitive specification) or in 
the data list of a GET statement, provided 
that it is neither enclosed within nor 
immediately followed by an argument list* 
(This does not apply to the names OPCHAR, 
ONSOURCE, and PRIORITY which are pseudo- 
variables that do not require arguments.) 
For example, if the statement SQRT = 1 had 
appeared in procedure B instead of the 
explicit declaration, SQRT would have been 
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contextually declared as a floating-point 
decimal variable. 



A user can even use a built-in function 
name as the entry name of a user-written 
function and, in the same program, use both 
the built-in function and the user-written 
function. This can be accomplished by use 
of the BUILTIN attribute and the ENTRY 
attribute. (The ENTRY attribute, which is 
used in a DECLARE statement to specify that 
the associated identifier is an entry name, 
is discussed in a later section of this 
section. ) 

The following example illustrates use of 
the ENTRY attribute in conjunction with the 
BUILTIN attribute. 

SQRT: PROCEDURE (PARAM) FIXED (6,2); 
DECLARE PARAM FIXED (12); 



If a user-written function using the 
name of a built-in function is external , 
any procedure containing a reference to 
that function name must also contain an 
entry declaration of that name; otherwise a 
reference to the identifier would be a 
reference to the built-in function. In the 
above example, if the PROCEDURE B were not 
contained in A, there would be no need to 
specify the BUILTIN attribute; so long as 
the identifier SQRT is not known as some 
other name, the identifier would refer to 
the built-in function. 

If a user-written function using the 
name of a built-in function is internal , 
any reference to the identifier in the con- 
taining block would be a reference to the 
user-written function, provided that its 
name is known in the block in which the 
reference is made. No entry name attri- 
butes would have to be specified if attri- 
butes to the returned value could be 
inferred from the entry name. 



END SQRT; 



A: PROCEDURE; 

DECLARE SQRT ENTRY RETURNS 

(FIXED(6,2)), Y FIXED(i2); 



X = SQRT(Y) ; 



RELATIONSHIP OF ARGUMENTS AND PARAMETERS 

When a function or subroutine is 
invoked, a relationship is established 
between the arguments of the invoking 
statement or expression and the parameters 
cf the invoked entry point. This relation- 
ship is dependent upon whether or not dummy 
arguments are created. 



B: BEGIN; 

DECLARE SQRT BUILTIN; 



SQRT (P); 



END B; 



END A; 

The use of SQRT as the label of the 
first PROCEDURE statement is an explicit 
declaration of the identifier as an entry 
name. Since, in this case, SQRT is not the 
built-in function, the entry name must be 
explicitly declared in A (and the RETURNS 
attribute is specified because the attri- 
butes of the returned value are not 
apparent in the function name) . r Jhe func- 
tion reference in the assignment statement 
in A thus refers to the user-written SQRT 
function. In the begin block, the identi- 
fier SQRT is declared with the BUILTIN 
attribute. Consequently, the function 
reference in the assignment statement in B 
refers to the built-in SQRT function. 



DUMMY ARGUMENTS 

In the introductory discussion of argu- 
ments and parameters, it is pointed out 
that the name of an argument, not its 
value, is passed to a subroutine or func- 
tion. However, there are times when an 
argument has no name. A constant, for 
example, has no name; nor does an opera- 
tional expression. But the mechanisrr that 
associates arguments with parameters cannot 
handle such values directly. Therefore, 
the compiler must provide storage for such 
values and assign an internal narre for 
each. These internal names are called 
dummy arguments . They are not accessible 
to the PL/I user, but he should be aware cf 
their existence because any change to a pa- 
rameter will be reflected only in the value 
cf the dummy argument and not in the value 
of the original argument from which it was 
constructed. 

A dummy argument is always created fcr 
any cf the following cases: 

1. If an argument is a constant 

2. If an argument is an expression 
involving operators 
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3. If an argument is an expression in 
parentheses 

4. If an argument is a variable whose 
data attributes are different from the 
data attributes declared for the pa- 
rameter in an entry name attribute 
specification appearing in the invok- 
ing block 

5. If an argument is itself a function 
reference containing arguments 

6. If, for the TSS/360 PL/I compiler, an 
argument is a controlled array or 
string associated with a simple param- 
eter, unless the asterisk notation is 
used. 

In all other cases, the argument name is 
passed directly. The parameter becomes 
identical with the passed argument; thus, 
changes to the value of a parameter will be 
reflected in the value of the original 
argument only if a dummy argument is not 
passed. 

A task variable cannot be passed as an 
argument if this would cause a dummy argu- 
ment to be created. 

Note : When a dummy argument is created for 
an argument that is a constant, the attri- 
butes of the dummy argument will be those 
indicated by the constant. For example, if 
SUB is a subroutine that expects to be 
passed a fixed binary argument, the 
statement 

CALL SUBC2) ; 

will lead to error, since the dummy argu- 
ment will be fixed decimal. This can be 
avoided either by assigning the value 2 to 
a fixed binary variable and passing the 
variable name, e.g., 

1=2; 

CALL SUB (I) ; 

or by using the ENTRY attribute. 



THE ENTRY ATTRIBUTE 

There is no way during compilation of a 
subroutine or function that the compiler 
can know the attributes of arguments that 
will be passed to a parameter. The compil- 
er must assume that the attributes of each 
argument will agree with the attributes of 
its associated parameter. Wherever there 
is disagreement, the program must provide, 
in the invoking procedure, an ENTRY attri- 
bute declaration for the entry name of the 
subroutine or function being invoked. The 
general form of the ENTRY attribute is as 
follows: 



ENTRY ( (parameter-attribute-list 
( , parameter-attribute-list] . , . ) ) 

Note that the above format allows the 
keyword ENTRY to be specified without 
accompanying parameter attribute lists, as 
it might be used to identify a function 
entry name that does not require arguments. 

Each parameter attribute list in the 
ENTRY attribute specification corresponds 
to one parameter of the subroutine or func- 
tion involved and specifies the attributes 
of that parameter. In general, if the 
attributes of an argument do not agree with 
those of its corresponding parameter (as 
specified in a parameter attribute list), a 
dummy argument is constructed for that 
argument if conversion is possible. The 
dummy argument contains the value cf the 
original argument converted to conform with 
the attributes of the corresponding parame- 
ter. Thus, when the subroutine or function 
is invoked, it is the dummy argument that 
is passed to it. 

If an ENTRY attribute with parameter 
attribute lists is not used, the compiler 
assumes that the arguments are compatible 
and acts according to the default attri- 
butes cf the parameters. if the argument 
attributes do not agree with the attributes 
cf the corresponding parameter, no conver- 
sion occurs, and an error probably results. 
For example, if a fixed decimal argurrent, 
which should be byte aligned, is passed to 
a procedure which expects a fixed binary 
arguirent, then a specification interruption 
probably occurs when the argument is 
treated as fullword binary. 

When the above form of the ENTRY attri- 
bute is used, each parameter of the subrou- 
tine or function must be accounted for. If 
there is no need to specify the attributes 
of a particular parameter, its place must 
be kept by a comma. For example, the 
statement: 

DECLARE SUBR ENTRY (FIXED, , FLOAT) ; 

specifies that SUBR is an entry narre that 
has three r ara " i eters; the first and third 
have the attributes FIXED and FLOAT, re- 
spectively, while the attributes of the 
second are presumably the same as those of 
the arguirent being passed. Since the 
attributes of the second parameter are net 
stated, no assumptions are made and no con- 
versions are performed. 

As mentioned earlier, the ENTRY attri- 
bute may be specified without parameter 
attribute lists. It is used in this way to 
indicate that the associated identifier is 
an entry name. Such an indication is 
necessary if an identifier is not otherwise 
recognizable as an entry name, that is, if 
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it is not explicitly or contextually 
declared tc be an entry name in one of the 
following ways: 

1. By its appearance as a label of a PRO- 
CEDURE or ENTRY statement (explicit) 

2. By its appearance immed lately follow- 
ing the keyword CALL (contextual) 

3. By its appearance as the function name 
in a function reference that contains 
an argument list (contextual) 

Therefore, if a reference is made to an 
entry name in a block in which it does not 
appear in one of these three ways, the 
identifier roust be given the ENTRY attri- 
bute explicitly, or by implication (see 
"Note" below) , in a DECLARE statement 
within the block. For example, assume that 
the following has been specified: 

A: PROCEDURE; 



PUT LIST (RANDOM) ; 



END A; 

Assume also that A is an external proce- 
dure and RANDOM is an external function 
that requires no arguments and returns a 
random number . As the procedure is shown 
above, RANDOM is not recognizable within A 
as an entry name, and the result of the PUT 
statement therefore is undefined. In order 
for RANDOM to be recognized within A as an 
entry name, it must be declared to have the 
ENTRY attribute. For example; 

A: PROCEDURE; 

DECLARE RANDOM ENTRY; 



PUT LIST (RANDOM) ; 



Entry Naires as Argument s 

When an entry name is specified as an 
argument of a function or subroutine 
reference, one of the following applies: 



1. If the entry name argument, call it M, 
is specified with an argument list of 
its own, it is recognized as a func- 
tion reference; M is invoked, and the 
value returned by M effectively 
replaces M and its argument list in 
the containing argument list. 

2. If the entry name argument appears 
without an argument list, but within 
an operational expression or within 
parentheses, then it is taken to be a 
function reference with no arguments. 
For example: 

CALL A((B)) ; 

This passes, as the argument to proce- 
dure A, the value returned by the 
function procedure B. 

3. If the entry name argument appears 
without an argument list and neither 
within an operational expression nor 
within parentheses, the entry name 
itself is passed to the function or 
subroutine being invoked. In such 
cases, the entry name is not taken to 
be a function reference, even if it is 
the name of a function that does not 
require arguments. For example: 

CALL A(B) ; 

This passes the entry name B as an 
argument to procedure A. 

There is an exception to this rule, 
however: if an identifier is known as 
an entry name and appears as an argu- 
ment and if the parameter attribute 
list for that argument specifies an 
attribute other than ENTRY, the entry 
name will be invoked and its returned 
value passed. For example: 



END A; 

Now, RANDOM is recognized as an entry 
name, and the appearance of RANDOM in the 
PUT statement cannot be interpreted as 
anything but a function reference. There- 
fore, the PUT statement results in the out- 
put transmission of the random number 
returned by RANDOM. 

Note : The ENTRY attribute is implied — 
and therefore need not be stated explicitly 
— for an identifier that is d^ blared in a 
DECLARE statement to have the RETURNS 
attribute. 



PROCEDURE; 

DECLARE B ENTRY, 

C ENTRY (FLOAT) ; 



X = C(B); 



END A; 

In this case, B is invoked and its 
returned value is passed to C. 
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Consider the following example: 

CALLP: PROCEDURE; 

DECLARE RREAD ENTRY, 

SUBR ENTRY (ENTRY, FLOAT, 
FIXED BINARY, LABEL); 



GET LIST CR # S> ; 



CALL SUBR (RREAD, SQRT (R) , S, 
LABI); 



the second parameter, as specified in 
the parameter attribute list declara- 
tion. When SUBR is invoked, the dummy 
argument is passed to it. 



LABI : CALL ERRT ( S ) ; 



END CALLP ; 

SUBR: PROCEDURE (NAME, X, J, TRANPT) ; 

DECLARE NAME ENTRY, TRANPT LABEL; 



IF X > J THEN CALL NAME (J) ; 
ELSE GO TO TRANPT; 



END SUBR; 

In this example, assume that CALLP, 
SUBR, and RREAD are external. In CALLP, 
both RREAD and SUBR are explicitly declared 
to have the ENTRY attribute. (Actually, 
the explicit declaration for SUBR is used 
principally to provide information about 
the characteristics of the parameters of 
SUBR.) Four arguments are specified in the 
CALL SUBR statement. These arguments are 
interpreted as follows: 

1. The first argument, RREAD, is recog- 
nized as an entry name (because of the 
ENTRY attribute declaration) . This 
argument is not in conflict with the 
first parameter as specified in the 
parameter attribute list in the ENTRY 
attribute declaration for SUBR in 
CALLP. Therefore, since RREAD is rec- 
ognized as an entry name and not as a 
function reference, the entry name is 
passed at invocation. 

2. The second argument, SQRT(R), is rec- 
ognized as a function reference 
because of the argument list accom- 
panying the entry name. SQRT is 
invoked, and the value returned by 
SQRT is assigned to a dummy argument, 
which effectively replaces the 
reference to SQRT. The attributes of 
the dummy argument agree with those of 
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4. The fourth argument, LABI, is a 

statement-label constant. Its attri- 
butes agree with those of the fourth 
parameter. But since it is a con- 
stant, a dummy argument is created for 
it. When SUBR is invoked, the dummy 
argument is passed. 

In SUER, four parameters are explicitly 
declared in the PROCEDURE statement. If no 
further explicit declarations were given 
for these parameters, arithmetic default 
attributes would be supplied for each. 
Therefore, since NAME must represent an 
entry name, it is explicitly declared with 
the ENTRY attribute, and since TRANPT must 
represent a statement label, it is expli- 
citly declared with the LABEL attribute. X 
and J are arithmetic, so the defaults are 
allowed to apply. 

Note that the appearance of NAME in the 
CALL statement does not constitute a con- 
textual declaration of NAME as an entry 
name. Such a contextual declaration can be 
made only if no explicit declaration app- 
lies, and the appearance of NAME in the 
PROCEDURE statement of SUBR constitutes an 
explicit declaration of NAME as a parame- 
ter. If the attributes of a parameter are 
not explicitly declared in a complementary 
DECLARE statement, arithmetic, defaults 
apply. Consequently, NAME must be expli- 
citly declared to have the ENTRY attribute; 
otherwise, it would be assumed to be a 
binary fixed-point variable, and its use in 
the CALL statement would result in an 
error. 



ALLOCATION OF PARAMETERS 
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A simple parameter may be associated 
with an argument of any storage class. 
However, if more than one generation of the 
argument exists, the parameter is asso- 
ciated only with that generation existing 
at the time of invocation. 

A controlled parameter must always have 
a corresponding controlled argument. Such 
an argument cannot be subscripted, cannot 
be an element of a structure, and cannot 
cause a dummy to be created. If more than 
one generation of the argument exists at 
the time of invocation, the parameter 
corresponds to the entire stack of these 
generations . Thus, at the time of invoca- 
tion, a controlled parameter represents the 
current generation of the corresponding 
argument. A controlled parameter can be 
allocated and freed in the invoked proce- 
dure, thus allowing the manipulation of the 
allocation stack of the associated argu- 
ment. A simple parameter cannot be speci- 
fied in an ALLOCATE or FREE statement. 

Parameter Bounds, Lengths, and Sizes 

If an argument is a string,, array, or 
area, the length of the string, the bounds 
of the array, or the size of the area must 
be declared for the corresponding parame- 
ter . The number of dimensions and the 
bounds of an array parameter, the length of 
a string parameter, or the size of an area 
parameter must be the same as that for the 
current generation of the corresponding 
argument. Usually , this can be ensured 
simply by specifying actual numbers for the 
bounds, length, or size of the parameter. 
However, the actual bounds, length, or size 
may not always be known at the time that 
the subroutine or function is written. 
Whenever this is the case, bounds, length, 
or size for a simple parameter can be spec- 
ified by asterisks,- bounds, length, or size 
for a controlled parameter can be specified 
either by asterisks or by expressions. 

Simple Parameter Bounds,, Lengths , and Sizes 



I When the actual length, bounds, or size 
of a simple parameter is not known, it can 

be specified in a DECLARE statement by 
asterisks. When an asterisk is used, the 
1 length, size, or bounds is taken from the 
current generation of the corresponding 
argument; if no current generation exists, 
any reference to the variable is an error. 
If an asterisk is used to represent the 
bounds of one dimension of an arra/ parame- 
ter, the bounds of all other dimensions of 
that parameter must be specified by 
asterisks. 

I Controlled Parameter Bounds, Le ngths, and 
Sizes 

The bounds, length, or size of a con- 
trolled parameter can be represented in a 



DECLARE statement either by asterisks or by 
element expressions. 



Asterisk Notation : When asterisks are 
1 used, size, length, or bounds of the con- 
trolled parameter is taken from the current 
generation of the corresponding argument. 
Any subsequent allocation of the controlled 
parameter uses the same bounds, length, or 

I size, unless it is overridden by a dif- 
ferent bounds, length, or size specifica- 
tion in the ALLOCATE statement. If no cur- 
rent generation of the argument exists, the 
asterisks only determine the dimensionality 
of the parameter, and an ALLOCATE statement 
in the invoked procedure must specify 
| bounds, length, or size for the controlled 
parameter before other references to the 
parameter can be made. 

Expression Notation : The bounds, length, 
1 or size of a controlled parameter can also 
be specified by element expressions. These 
expressions are evaluated at the time of 
allocation. Each time the parameter is 
allocated, the expressions are re-evaluated 
1 to give current bounds, length, or size for 
the new allocation. However, such expres- 
sions in a DECLARE statement can be over- 
I ridden by a bounds, length, or size speci- 
fication in the ALLOCATE statement itself. 

If a current generation of the argument 

exists at the time of invocation, the ex- 
pressions evaluated at invocation must give 

I the same bounds, length, or size as the 
argument. If a current generation .does not 
exist, then no requirements are made on the 
values of these expressions. They are 
evaluated each time the parameter is allo- 
cated, except in those cases where the ex- 
pressions are overridden by a bounds, 

i length, or size specification in the ALLOC- 
ATE statement itself. For example: 

MAIN: PROCEDURE OPTIONS (MAIN) ; 

DECLARE (A(20) f BOO), C(100), 
D C 1 ) ) CONTROLLED , 
NAME CHARACTER 120), 
I FIXEDC3, DE- 



ALLOCATE A, B; 
CALL SUB1 CA f B) ; 



FREE A, B; 



FREE A,B? 

GET LIST (NAME, I) ; 

CALL SUB2 (C,D,NAME, I); 



FREE C,D; 
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END MAIN; 

SUBls PROCEDURE CU f V); 

DECLARE (0(*>, ¥C*>> CONTROLLED,* 



ALLOCATE UC30), V(«l0); 



RETURN; 
END SUBl; 

SOB2s PROCEDURE IX, Y, NAMEA f N) ; 

DECLARE CXCN) ,Y(N>> CONTROLLED, 
NAMEA CHARACTER C*>, 

N FIXED 13,0) ; 



ALLOCATE X f Y; 



RETURN; 

END SUB2; 

In the procedure MAIN, the arrays A # B f C f 
and D are declared with the CONTROLLED 
storage class attribute? NAME and I are 
AUTOMATIC by default. 

When SUB1 is invoked, A and B f which 
have been allocated as declared f are 
passed* SUB1 declares its parameters with 
the asterisk notation. The ALLOCATE state- 
ment, however, specifies bounds for the 
arrays; consequently, the allocated arrays, 
which are actually a second generation of A 
and B, have bounds different from the first 
generation Cif no bounds were specified in 
the ALLOCATE statement, the bounds of the 
new generation would be identical to those 
of the first generation) . 

After control returns to MAIN, the first 
FREE statement frees the second generation 
of A and B (allocated in SUB1 as parame- 
ters) , and the second FREE statement frees 
the first generation (allocated in MAIN). 

When SUB2 is invoked, C and D are passed 
to X and Y, NAME is passed to NAMEA, and I 
is passed to N* In SUB2, X and Y are 
declared with bounds that depend upon the 
value of I (passed to N) . When X and Y are 
allocated, this value determines the bounds 
of the allocated array. 

Although NAME (corresponding to NAM£&> 

is not controlled , the asterisk notation 
for the length of NAMEA indicates that the 
length is to be picked up from the declara- 
tion of the argument (NAME) - 



ARGUMENT AND PAHAMETEB TYPES 

In general, an argument and its corres- 
ponding parameter may be of any data 
organization and type. For example , an 
argument nay be a statement label, provided 
that the corresponding parameter is 
declared with the LABEL attribute; it may 
be an entry name, provided that the corres- 
ponding parameter is an entry name, and so 
on. However, not all parameter/argument 
relationships are so clear-cut • Some need 
further definition and clarification « Such 
cases are given be- low. 



If a parameter is an element , i.e., a 
variable that is neither a structure nor an 
array, the argument must be an element 
expression* if the argument is a sub- 
scripted variable, the subscripts are eval- 
uated before the subroutine or function is 
invoked and the name of the specified ele- 
ment is passed. If the argument is a con- 
stant, the attributes of the corresponding 
parameter must agree with the attributes 
indicated by the constant, unless the ENTRY 
attribute is specified for the entry name, 

if a parameter is an array , the argument 
must be an array expression or an element 
expression. if the argument is an element 

expression, the corresponding parameter 
attribute list must specify the bounds of 
the array -parameter. (Note, however, that 
in this case the bounds in the parameter 

attribute list cannot be asterisks.) This 
causes the construction of a dummy array 
argument, whose bounds are those of the 
array parameter* The value of the element 
expression tj^n becomes the value of each 
element of the dummy array argument* 

if a parameter is a structure , the argu- 
ment must be a structure expression or an 
element expression. If the argument is an 
element expression, the corresponding pa- 
rameter attribute list must specify the 
structure description of the structure pa- 
rameter (only l&vel numbers need be used - — 
see the discussion of the ENTRY attribute 
in Part II, Section 9 f ' "Attributes," for 
details). This causes the construction of 
a dummy structure argument, lAose descrip- 
tion matches that of the structure parame- 
ter* The value of the element expression 
then becomes the value of each element of 
the dummy structure argument. The relative 
structuring of the argument and the parame- 
ter must be the same; the level numbers 
need not be identical. The element value 
must be one that can be converted to con- 
form with the attributes of all the elemen- 
tary names of the structure. 

if a parameter is an ^ement l abel vari- 
able , 'the argument must, be either an ele- 
ment label variable or f* label constant. 
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If the argument is a label constant, a 
dummy argument is constructed. 



C=B || • 45 f ; 

/* C= , 123bb' NOT 



'12345 1 */ 



If the parameter is an ar ray label vari- 
able , the argument must be an array label 
variable, an element label variable, or a 
label constant. If the argument is either 
of the latter two, the corresponding param- 
eter attribute list must specify that the 
parameter is a label array, giving the 
bounds of that array. This causes the con- 
struction of a dummy array label argument, 
whose bounds are those of the label array 
parameter. 



If a parameter is an entry name , the 
argument must be an entry name. Note that 
the name of a mathematical built-in func- 
tion can be passed as an argument, but no 
other built-in function names can be 
passed. 

If a parameter is a file name , the argu- 
ment must be a file name. The attributes 
of the file name parameter are always 
ignored. 

If a parameter is a fixed-length string 
variable, the argument should be a fixed- 
length string. If the argument is of vary- 
ing length, a parameter attribute list 
describing the parameter as a fixed-length 
string must be given in the invoking proce- 
dure. Similarly, if a parameter is a 
varying-length string variable, the argu- 
ment should be a varying-length string. If 
the argument is of fixed length, a parame- 
ter attribute list describing the parameter 
as a varying-length string must be given in 
the invoking procedure. Whenever a 
varying-length string argument is passed to 
a non-varying string parameter whose length 
is undefined (i.e., specified by an 
asterisk), the maximum length of the argu- 
ment is passed to the invoked procedure. 
This is true even when the argument is an 
element; the object of passing the maximum 
length rather than the current length is to 
maintain a consistent rule for both element 
and array arguments. (If the argument were 
a varying-length string array passed to a 
non-varying undefined-length parameter, 
only one length could be passed, and this 
would naturally be the maximum length.) 

Example: 

DECLARE A CHARACTER ( 5 ) VARYING, 

PR0C1 ENTRY (CHARACTER ( < )) ; 

A= i 123 i ; 

CALL PR0C1 (A) ; 

PR0C1: PROCEDURE (B) ; 
DECLARE B CHARACTER (*) , 
C CHARACTER (5) ; 



In this example, to pass A, a dummy of 
length 50 (i.e., the maximum length of A) 
is created. In the concatenation opera- 
tion, '45' is concatenated at the right of 
the character string of length 50 (which 
contains ' 123' followed by 47 blanks). The 
result is then truncated to fit into C, 
which has length 5, so that C='123bb'. 

If a parameter is a locator variable of 
either pointer or offset type, the argument 
nust be a locator variable of either type. 
If the types differ, a dummy argument is 
created. (See also Part I, Section 14, 
"Based Storage and List Processing. M ) 



GENERIC NAMES AND REFERENCES 

A generic name represents a family of 
procedure entry points, each member of 
which can be invoked by a generic 
reference , that is, a procedure reference 
using the generic name in place of the 
actual entry name. The member invoked is 
determined according to the number and 
attributes of the arguments specified in 
the generic reference; it is that member 
whose parameters match the arguments in 
number and attributes. 

A generic name must be declared with the 
GENERIC attribute. The general format of 
this attribute is as follows: 

generic-name GENERIC (member-declaration 
[ , member-declaration] . . . ) 

Each member declaration corresponds to 
cne procedure entry point in the family. 
It specifies the entry name of the irember, 
followed by the ENTRY attribute and its 
associated parameter attribute list; this 
list gives the number and attributes of the 
parameters for that entry name. Fcr 
example, consider the following statement: 



DECLARE CA1C GENERIC 

(FXDCAL ENTRY (FIXED, FIXED) , 
FLOCAL ENTRY (FLOAT, FLOAT ) , 
MIXED ENTRY (FLOAT, FI XED )) ; 

This statement defines CALC as a generic 
name having three members, FXDCAL, FLOCAL, 
and MIXED. One of these three function 
procedures will be invoked by a generic 
reference to CALC, depending on the charac- 
teristics of the two arguments in that 
reference. For example, consider the fol- 
lowing statement: 

Z= X + CALC(X,Y); 
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If X and Y are floating-point and fixed- 
point, respectively, MIXED will be invoked. 



PLI TOMMOD 

TOM: PBGC (PARAM) OPTIONS (MAIN); 
DCL PARAM CHAR (100) VARYING; 



PASSING AN ARGUMENT TO THE MAIN PROCEDURE 



When invoking a procedure, a single 
argument can be passed in apostrophes, 
using the operand field of the procedure 
name. See IBM System/360 Time Sharing Sys- 
tem, PL/I Programmer's Guide . If this 
facility is used, the first argument should 
be declared as a VARYING character string; 
the maximum length is 100, and the current 
length is set equal to the argument length 
at object time. The argument can also be a 
fixed-length character string. For 
example: 



END; 
END 



After compiling TOM, the user can execute 
it by issuing the statement TOMMOD 
, ABC123 i . The length of PARM is set equal 
to 6, and the character string ABC123 is 
passed to TOM. 
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SECTION 13: 



EXCEPTIONAL CONDITION HANDLING AND PROGRAM CHECKOUT 



When a PL/I program is executed, a large 
number of exceptional conditions are mon- 
itored by tine system and their occurrences 
are automat ically detected whenever they 
arise. These exceptional conditions may be 
errors, such as overflow or an input/output 
transmission error, or they may be condi- 
tions that are expected tut infrequent, 
such as the end of a file or the end of a 
page when output is being printed. When 
checking out a program, a user can also get 
a selective flow trace and dumps by speci- 
fying that the occurrence of any one of a 
list of identifiers be treated as an excep- 
tional condition. 

Each of the conditions for which a test 
may be made has been given a name, and 
these names are used by the user to control 
the handling of exceptional conditions. 
The list of condition names is part of the 
PL/I language. For keyword names and 
descriptions cf each of the conditions, see 
Part II, Section 8, W ON-Conditions. " 



ENABLED CONDITIONS AND ESTABLISHED ACTION 



of the computational conditions and the 
program checkout conditions may be enabled 
or disabled. The program checkout condi- 
tions and the SIZE condition must be ex- 
plicitly enabled if they are to cause an 
interruption; all other conditions are 
enabled by default and must be explicitly 
disabled if they are not to cause an inter- 
ruption when they occur. 

Condition Prefixes 

Enabling and disabling can be specified 
for certain conditions by a condition pre- 
fix. A condition prefix is a list of one 
cr more condition names, enclosed in paren- 
theses and separated by commas, and con- 
nected tc a statement Cor a statement 
label) by a colon. The prefix always pre- 
cedes the statement and any statement 
labels. A condition name in a prefix list 
indicates that the corresponding condition 
is enabled within the scope of the prefix. 
Some condition names can be preceded by the 
word NO, without a separating blank or con- 
nector, to indicate that the corresponding 
condition is disabled. 



A condition that is being monitored, and 
the occurrence of whicn will cause an 
interruption, is said to be enabled . Any 
action specified to take place when an 
occurrence of the condition causes an 
interruption, is said to be established . 

Most conditions are checked for automat- 
ically, and when they occur, the system 
will take control and perform some standard 
action specified for the condition. These 
conditions are enabled by default, and the 
standard system action is established for 
them. 

The most common system action is to 
raise the ERROR condition. This provides a 
common condition that may be used to check 
for a number of different types of errors, 
rather than checking each error type indi- 
vidually. Standard system action for the 
ERROR condition is tc raise the FINISH con- 
dition and terminate the task. 

The user may specify whether 01 not some 
conditions are to be enabled, that is, are 
to be checked for so that they will cause 
an interruption when they arise. If a con- 
dition is disabled, an occurrence of the 
condition will not cause an interruption. 

All input/output conditions and the 
ERROR, FINISH, and AREA conditions are 
always enabled and cannot be disabled. All 



Scope of the Condition Prefix 

Tne scope of the prefix, that is, the 
part of the program throughout which it 
applies, is usually the statement to which 
the prefix is attached. The prefix does 
not apply to any functions or subroutines 
that may be invoked in the execution of the 
statement. 

A condition prefix to an IF statement 
applies only to the evaluation of the 
expression following the IF; it does net 
apply to the statements in the THEN or ELSE 
clauses, although these may tnercselves have 
prefixes. Similarly, a prefix to the ON 
statement has no effect on the statements 
in the on-unit. A condition prefix to a DO 
statement applies only to the evaluation of 
any expressions in the DO statement itself 
an & not to any other statement in the D0- 
group. 
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The enabling or disabling of a condition 
nay be redefined within a block by attach- 
ing a prefix to statements within the 
block, including PROCEDURE and BEGIN state- 
ments (thus redefining the enabling or dis- 
abling of the condition within nested 
blocks). Such a redefinition applies only 
to the execution of the statement to which 
the prefix is attached. In the case of a 
nested PROCEDURE 01 BEGIN statement, it 
applies only to the block the statement 
defines, as well as any blocks contained 
within that block. When control passes out 
of the scope of th* redefining prefix, the 
redefinition no longer applies. A condi- 
tion prefix can be attached to any state- 
ment except a DECLARE or ENTRY statement. 



The ON Statement 
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The single statement on-unit, or the 
begin blcck on-unit, is executed as though 
it were a procedure (without parameters) 
that was called at the point in the program 
at which the interruption occurred. If the 
on-unit is a single statement it behaves 
exactly as though it were enclosed by PRO- 
CEDURE and END statements; when execution 
reaches the END statement of the unit, con- 
trol returns to the point from which the 
block was invoked. Just as with a proce- 
dure, control may be transferred out of an 
cn-unit by a GO TO statement; in this case, 
control is transferred to the point speci- 
fied in the GO TO, and a normal return does 
not occur. 



Note: The action specified in an ON state- 
ment will not be executed during any por- 
tion of a program throughout which the con- 
dition has been disabled. 

The form of the ON statement is: 

ON condition-name [SNAP) on-unit 

SYSTEM; 



(See Part II, Section J, 
full description.) 
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The keyword SYSTEM followed by a semi- 
colon specifies standard system action 
whenever an interruption occurs. It rees- 
tablishes system action for a condition for 
which some other action has been estab- 
lished. The on-unit is used by the user to 
specify an alternate action to be taken 
whenever an interruption occurs. 
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A special case of an on-unit is the null 
statement. The effect of this is to say 
"when an interruption occurs as a result of 
this condition, do nothing. m 

Use of the null on-unit is not the same 
as disabling, for two reasons: first , a 
null on-unit may be specified for any con- 
dition, but not all conditions can be dis- 
abled; and, second, disabling a condition, 
if possible, may save time by avoiding any 
checking for this condition. If a null 
cn-unit is specified, the system must still 
check for occurrence of the condition, 
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transfer control to the on-unit whenever an 
interruption occurs, and then, after doing 
nothing, return from the on-unit. 

| Note: With the TSS/360 PL/I compiler, a 
null on-unit for the CONVERSION condition 
will not cause a permanent loop if a con- 
version error occurs, because no conversion 
is re-attempted unless the invalid charact- 
er is changed in the on-unit. If it is not 
changed, the ERROR condition is raised. 



Scope of the ON Statement 

The execution of an ON statement asso- 
ciates an action specification with the 
named condition. Once this association is 
established, it remains until it is over- 
ridden or until termination of the block in 
which the ON statement is executed. 

An established interruption action 
passes from a block to any block it acti- 
vates, and the action remains in force for 
all subsequently activated blocks unless it 
is overridden by the execution of another 
ON statement for the same condition. If it 
is overridden, the new action remains in 
force only until that block is terminated. 
When control returns to the activating 
block, all established interruption actions 
that existed at that point are reestab- 
lished. This makes it impossible for a 
subroutine to alter the interruption action 
established for the block that invoked the 
subroutine. 

If more than one ON statement for the 
same condition appears in the same block, 
each subsequently executed ON statement 
permanently overrides the previously estab- 
lished condition. No reestatlishment is 
possible, except through execution of 
another ON statement with an identical 
action specification Cor re-execution, 
through some transfer of control, of an 
overridden ON statement) . 

The REVERT Statement 

The REVERT statement is used to cancel 
the effect of one or more previously 
executed ON statements. It can affect only 
ON statements that are internal to the 
block in which the REVERT statement occurs 
and which have been executed in the same 
invocation of that block. The effect of 
the REVERT statement is to cancel the 
effect of any ON statement for the named 
condition that has been executed in the 
same block in which the REVERT statement is 
executed. It then reestablishes the action 
that was in force at that time of activa- 
tion of that block. This statement has the 
form: 

REVERT condition- name; 



A REVERT statement that is executed in a 
block in which no on-unit has been estab- 
lished for the named condition is treated 
as a null statement. 



The SIGNAL Statement 

The user may simulate the occurrence of 
an ON condition by means of the SIGNAL 
statement. An interruption will occur 
unless the named condition is disabled. 
This statement has the form: 

SIGNAL condition- name; 

The SIGNAL statement causes execution of 
the interruption action currently estab- 
lished for the specified condition. The 
principal use of this statement is in pro- 
gram checking, to test the action of an 
on-unit, and to determine that the correct 
action is associated with the condition. 

If the signaled condition is not 
enabled, the SIGNAL statement is treated as 
a null statement. 

The CONDITION Condition 

The ON-condition of the form: 

CONDITION (identifier) 

allows a user to establish an on-unit that 
will be executed whenever a SIGNAL state- 
ment is executed specifying CONDITION and 
that identifier. 

As a debugging aid, this condition can 
be used to establish an on-unit whose 
execution results in printing information 
that shows the current status of the pro- 
gram. The advantage of using this tech- 
nique is that the statements of the on-unit 
need be written only once. They can be 
executed from any point in the program 
through placement of a SIGNAL statement. 

Following is an example of how the CON- 
DITION condition might be included in a 
program: 

ON CONDITION (TEST) BEGIN; 



END; 

Execution of the begin block would be 
caused wherever the following statement 
appears: 

SIGNAL CONDITION (TEST) ; 

The CONDITION condition always is 
enabled, but it can be raised only by the 
SIGNAL statement. 
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The CHECK Condition 

The CHECK condition is an important tool 
provided in PL/I for program testing. The 
keyword CHECK in a prefix list is followed 
by a parenthesized name list. The names in 
the list may be statement label constants, 
entry names, and variables, including array 
and structure variables, label variables, 
task variables, event variables, area 
variables, and locator variables. Sub- 
scripted names are not allowed but quali- 
fied names can be used. Parameters, and 
variables with the DEFINED or EASED attri- 
butes cannot be checked. 

The CHECK prefix may be attached only to 
PROCEDURE or EEGIN statements, and there- 
fore, it always applies to an entire block. 

An interruption will generally occur 
immediately after the execution of a state- 
ment in which the value of a variable in a 
check list may have been altered. Excep- 
tions are as follows: 

1. With the compiler, during data- 
directed input, the interruption 
occurs after the first checked vari- 
able receives its value. 

2. With statement labels and entry names, 
the interruption occurs immediately 
before the execution of the statement 
or the invocation of the entry name. 

The system action for the CHECK condition 
is to print the identifier causing the 
interruption and, if it is a variable 
(other than a program control variable) , to 
print its new value in the form of data- 
directed output. For label variables and 
other program control variables, only the 
variable is printed; no value is included. 

Thus, by preceding a block with a CHECK 
prefix, as shown in the example in Figure 
18, the user can obtain selective dumps in 
a readable format by specifying variables; 

he can obtain a flow trace oy specifying 
labels and entry names. 

The CHECK condition may also be speci- 
fied in an ON statement, if other than sys- 
tem action is required. This gives the 
user all the facilities of PL/I, including 
the simplicity of data-directed output for 
controlling and editing his debugging 
information. 

The SUBSCRIPTRANGE Condition 

Another ON condition that is used prin- 
cipally for program checkout, but that may 
also be used in production, is the SUB- 
SCRIPTRANGE condition. This condition must 
be enabled in a condition prefix. When it 
is enabled, each subscript in an array 



reference is checked every time it is eval- 
uated to see that it lies within the speci- 
fied bounds. The condition is raised if 
any subscript is too high or too low. 

Since this checking involves a substan- 
tial overhead, it usually is used only in 
program testing, and is removed for produc- 
tion programs. 

The STRINGRANGE Condition 
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Condition Built-in Functions and Condition 
Codes 

When an on-unit is invoked, it is as if 
it were a procedure without arguments. It 
is therefore impossible to pass to the on- 
unit any information about the interruption 
(other than the name of the condition) . To 
assist the user in making use of on-units, 
some special functions are provided that 
rray be used to inquire about the cause of 
an interruption and possibly to atteirpt to 
correct the error. 

These condition built-in functions can 
be used only in on-units or in blocks 
invoked by on-units. They are listed in 
Part II, Section 7, "Built-in Functions and 
Pseudo- Variables . w 

The condition built-in functions provide 
information such as the name of the proce- 
dure in which the interruption occurred, 
the character or character string that 
caused a conversion interruption, the value 
of the key used in the last record trans- 
mitted, e*nd so on. Some can be used as 
pseudo-variables for error correction. 

The ONCODE function provides a binary 
integer whose value depends on the cause of 
the last interruption. This function, used 
in conjunction with the ERROR condition, 
allows the user to deal with errors that 
may be detected by the implementation, but 
that are not represented by condition names 
in the language. 



EXAMPLE OF USE OF ON-CONDITIQNS 

The routine shown in Figure 18 illus- 
trates the use of the ON statement, the 
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(CHECK (HEADER, NEWBATCH, INPUT, BADBATCH, SAMPLE) ) : /*DEBUG*/ 01 

DIST: PROCEDURE; 02 

DECLARE 1 SAMPLE EXTERNAL, 03 

2 BATCH CHARACTERS) , 0*4 

2 SNO PICTURE ' 9999 f , 05 

2 READINGS CHARACTER (7 0) , 06 

TABLE (15, 15) EXTERNAL; 07 

/* ESTABLISH INTERRUPTION ACTIONS FOR ENDFILE & CONVERSION */ 08 

ON ENDFILE (PDATA) CALL SUMMARY; 09 

ON CONVERSION BEGIN; CALL SKIPBCH; 10 

GO TO NEWBATCH; 11 

END; 12 

ON ERROR DISPLAY (BATCH | | SNO| (READINGS); 13 

/* MAIN LOOP TO PROCESS HEADER S TABLE */ 14 

HEADER: READ INTO (SAMPLE) FILE (PDATA); 15 

PUT DATA (SAMPLE); /*DEBUG*/ 16 

/♦THE CHECK ACTION LISTS INPUT DATA FOR DEBUG*/ 

IF SNO t= THEN SIGNAL CONVERSION; 17 

NEWBATCH: GET LIST (OMIN ,OINT, AMIN, AINT) STRING (READINGS); 18 

TABLE =0; 19 

CALL INPUT; 20 

CALL PROCESS; 21 

GO TO HEADER; 22 

/* ERROR RETURN FROM INPUT */ 2 3 

BADBATCH: SIGNAL CONVERSION; 24 

( CHECK ( INI , IN2 , ERR2 , ERR1 , TABLE) ) : /+DEBUG*/ 25 

INPUT: PROCEDURE; 26 

/* ESTABLISH INTERRUPTION ACTIONS FOR CONVERSION & SUBRG */ 27 

ON CONVERSION BEGIN; 2 8 

IF ONCODE = 624 S ONCHAR = ■ ■ 29 

THEN DO; ONCHAR = 'O'; 30 

GO TO ERR1; 31 

END; 32 

ELSE GO TO BADBATCH; 33 

END; 34 

ON SUBSCRIPTRANGE GO TO ERR2; 35 

/* LOOP TO READ SAMPLE DATA AND ENTER IN TABLE */ 36 

INI: READ INTO (SAMPLE) FILE (PDATA); 37 

IF SNC = 9999 THEN RETURN; /*TRAILER CARD*/ 38 

IN2: GET EDIT (R, OMEGA, ALPHA) (3 P , 999 l ) 39 

STRI NG ( READINGS ) ; 40 

(SUBSCRIPTRANGE): TABLE ( (OMEGA-OMIN) /OINT, (AIPHA-AMIN) /AINT) = R; 41 

GO TO INI; 42 

/* FIRST CONVERSION fc SUBSCRIPTRANGE ERROR IN THIS BATCH */ 43 

ERR2: ON SUBSCRIPTRANGE GO TO BADBATCH; /*FOR NEXT ERROR*/ 44 

CALL ERRMESS (SAMPLE, 02) ; 45 

GO TO INI; 4 6 

ERR1: REVERT CONVERSION; /*SWITCH FOR NEXT ERROR*/ 47 

CALL ERRMESS (SAMPLE, 01); 48 

GO TO IN2; 49 

END INPUT; 50 

END DIST; 51 



Figure 18. A Program Checkout Routine 



SIGNAL and REVERT statements, and condition 
prefixes. The routine reads batches of 
card images containing test readings. Each 
batch has a header card with a sample num- 
ber, called SNO, of zero and a trailer card 
image with SNO equal to 9999. If a conver- 
sion error is found, one retry is attempted 
with the error character set to zero. Two 
data fields are used to calculate a sub- 
script; if the subscript is out of range, 
the sample is ignored. If th. re is more 



than one subscript error or more than one 
conversion error in a batch, that batch is 
then ignored. 

The numbers to the right of each line 
are sequence numbers, which are not part of 
the program itself. 

The CHECK prefixes in lines 1 and 25 are 
included to help with debugging; in a pro- 
duction {program, they would be removed. 
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The prefix specifies that just before the 
statements HEADER, NEWBATCH, and BADBATCH 
are executed, just before the procedure 

I INPUT is invoked, and whenever the value of 
the variable SAMPLE changes, interruptions 
will occur. Since no ON statement has been 
executed for the CHECK condition, system 
action is performed. This will result in 
the appropriate name being written on SYS- 

I PRINT, together with the new value, if any, 
Of SAMPLE. 



Since the labels used within the intern- 
al procedure INPUT are not known in DIST , 
they cannot be specified in a CHECK list 
for DIST. A separate CHECK prefix is 
therefore inserted just before the proce- 
dure statement heading INPUT. This check 
list specifies the labels in INPUT, and the 
array TABLE. 



It is worth noting again that the CHECK 
condition prefix can be applied only to 
PROCEDURE and BEGIN blocks, and not to 
individual statements. The first statement 
executed is on the ON ENDFILE statement on 
line 9. This specifies that the external 
procedure SUMMARY is to fce called when an 
ENDFILE interruption occurs. This action 
applies within DIST and within INPUT and 
within all other procedures called by DIST, 
unless they establish their own action for 
ENDFILE. 

Throughout the procedure, any conditions 
except SIZE, SUBSCRIPTRANGE, STRINGRANGE, 
and CHECK are enabled by default; and for 
all conditions except those mentioned ex- 
plicitly in ON statements, the system 
action applies. This system action, in 
most cases, is to generate a message and 
then to raise the ERROR condition. The 
action specified for the ERROR condition on 
line 13 is to display the contents of the 
card being processed. When the ERROR 
action is completed, the FINISH condition 
is raised, and execution of the program is 
terminated. 

The statement on line 10 specifies 
action to be taken whenever a CONVERSION 
interruption occurs. Since this action 
consists of more than one statement, it is 
bracketed by BEGIN and END statements. 

The main loop of the program starts with 
the statement HEADER. Since the CHECK con- 
dition is enabled for HEADER, an interrip- 
tion will occur before HEADER is executed. 
The READ statement with the INTO option 
will cause a CHECK condition to be raised 
for the variable specified in the INTO 
option C unless , for the TSS/360 compiler, 
the EVENT option is used) ; consequently, 
the input is listed in the form of data- 
directed output. 



The card image read is assumed to be a 
header card. If it is not, the SIGNAL CON- 
VERSION statement causes execution of the 
BEGIN block, which in turn calls a proce- 
dure (not shown here) that reads on, ignor- 
ing card images until it reaches a header 
card image. The begin block ends with a GO 
TO statement that terminates the on-unit. 
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The array TABLE is initialized to zero 
before the procedure INPUT is called. This 
procedure inherits the on-units already 
established in DIST, but it can override 
them. 



The first statement of INPUT establishes 
a new action for CONVERSION interruptions. 
Whenever an interruption occurs, the ONCODE 
is tested to check that the interruption is 
due to an illegal P format input character 
and that the illegal character is a blank. 
If the illegal character is a blank, it is 
replaced by a zero, and control is trans- 
ferred to ERR1. 

ERR1 is internal to the procedure INPUT. 
The statement, REVERT CONVERSION, nullifies 
the ON CONVERSION statement executed in 

INPUT and restores the action specified for 
conversion interrupts in DIST (which causes 
the batch to.be ignored). 

After a routine is called to write an 
error message, control goes to IN2, which 
retries the conversion. If another conver- 
sion error occurs, the interruption action 
is that specified on lines 10 and 11. 

The second ON statement in INPUT estab- 
lishes the action for a SUBSCRIPTRANGE 
interruption. This condition must be ex- 
plicitly enabled by a SUBSCRIPTRANGE prefix 
for an interruption to occur. If an inter- 
ruption does occur, the on-unit causes a 
transfer to ERR2, which establishes a new 
on-unit for SUBSCRIPTRANGE interruptions, 
overriding the action specified in the ON 
statement on line 35. Any subsequent sub- 
script errors in this batch will, there- 
fore, cause control to go to BADBATCH, 
which signals the CONVERSION condition as 
it existed in the procedure DIST. Note 
that on leaving INPUT, the on- act ion 
reverts to that established in DIST,, which 
in this case calls SKIPBCH to get to the 
next header card. 
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After establishment of a new on- unit, a 
message is printed, and a new sample card 
image is read. 

The statement labeled INI reads an 80- 
coluirn card image into the structure 
SAMPLE. A READ statement does not cause 
input data to be checked, so the CONVERSION 
condition cannot arise. 

The statement IN2 checks and edits the 
data in columns 11 through 19 according to 



the picture format item. A nonnumeric 
character (including blank) in these 
columns will cause a conversion interrup- 
tion, with the results discussed above. 

The next statement (line Ul) has a SUE- 
SCRIPTRANGE prefix. The data just read is 
used to calculate a double subscript. If 
either subscript falls outside the bounds 
declared for TABLE, an interruption occurs. 
If both fall outside the range, two inter- 
ruptions occur. 
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SECTION 14: EASED VARIABLES AND LIST PROCESSING 



This section describes the PL/I based 
storage facilities of the TSS/360 PL/I com- 
piler, and gives some indication of their 

use. 



INTRODUCTION 

Storage allocation is the association of 
the requisite amount of storage with a 
variable; it is effectively a two-way pro- 
cess: the stcrage is associated with a 
variable, and the variable is associated 
with the storage. Allocation will be made 
either statically (that is, before the pro- 
gram is executed) , or dynamically (that is f 
during execution). A statically allocated 
variable remains allocated for the duration 
of the program, but a dynamically allocated 
variable may relinquish its storage before 
the program has finished. 

The storage class attributes determine 
which kind of allocation is to apply to a 
given variable. STATIC specifies that 
allocation will be made statically; AUTO- 
MATIC, CONTROLLED, and BASED each specify a 
type of dynamic allocation. Automatic 
storage is allocated automatically on entry 
to the block in which the variable is 
declared, and freed automatically when the 
block is terminated; once freed, the value 
of the variable is lost. Controlled 
storage allocation is under the direct con- 
trol of the user, using the ALLOCATE and 
FREE statements. Based storage allocation 
is also under the direct control of the 
user, but with some essential differences 
from controlled allocation. 
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Whenever a based variable is allocated, 
a pointer variable is set to a value relat- 
ing to the address of the allocation; by 
including this pointer variable in a 
reference to the based variable, the user 
can distinguish between different alloca- 
tions of one based variable. In other 
words, reference to the based variable can 
be qualified by a pointer value. The 
pointer variable is one of two types of 



locator variable . The other type, the off- 
set variable, is discussed later. 

The based variable can be a structure 
containing a locator for another alloca- 
tion, which in turn can contain a locator 
for yet another allocation, and so en. 
This is the fundamental concept underlying 
PL/ I list processing; different allocations 
can be chained together in a specific 
order. In fact, they can be chained 
together in several different orders at 
ence by using several different sets of 
locators. Thus, for example, it is possi- 
ble to sort a list without duplicating the 
list items or moving them around; any 
sequence can be specified by a set of loca- 
tors. This facility can also be used to 
chain like items together without neces- 
sarily implying a particular order. 

A list or chain of associated based 
variables could be scattered over a large 
area of storage, linked only by pointers* 
However, to facilitate input/output and 
assignment, the based variables can be 
collected together into a reserved area . 
The relative locations of the items can 
then be established. The reason for this 
provision is that the value of a pointer is 
absolute and refers to only one allocation 
cf a variable; for example, if a list of 
associated based structures containing 
pointers were written out and later read in 
again, this would constitute a realloca- 
tion, within which the pointer values would 
be meaningless because the addresses would 
be different. However, another kind of 
locator variable, called an offset vari- 
able, is available, which establishes the 
location of an item relative to the start 
of an area. Because it is relative, the 
value of an offset variable retains its 
meaning across input /output and assignment. 

As well as providing a list processing 
facility, based storage allows the user to 
make more efficient use of record-oriented 
input/output. This type of input/output 
normally involves the use of intermediate 
buffers and work areas; but a based vari- 
able can be virtually overlaid on a buffer, 
and processing can take place within the 
buffer. Several separate based variables 
can be effectively overlaid on the same 
buffer at once; this allows easy handling 
of files containing different types of 
record. (The type of record would be des- 
ignated within the record itself;, the 
correct based variable could then be deter- 
mined from a test made after the record has 
teen read into the buffer,) This type of 
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input/output using based variables is the 
PL/I form of locate mode input/output . 



BASED VARIABLES AND POINTER VARIABLES 

A based variable is a variable that can 
be allocated in more than one location in 
storage, thus simultaneously representing a 
number of values, any of which can be 
retrieved by specifying a pointer variable 
associated with the relevant storage 
location. 



made equal to the X allocated in the loca- 
tion associated with Q. The appearance of 
P and Q in the statement contextually 
declares them as pointer variables, unless 

explicit declarations exist for P and Q. 

The arrow c or pointer qualifier, is a 
composite symbol made up of a minus sign 
followed by a greater- than sign. Its 
equivalent in the 48-character set is PT. 
It does not signify an operation; its func- 
tion is similar to that of the period sym- 
bol in an ordinary qualified name. 



When a based variable is declared, it is 
associated with a pointer variable. The 
form of the declaration is: 



identifier BASED (pointer-variable) 



Example : 

DECLARE X BASED (P); 

This declaration also contextually declares 
P to be a pointer variable unless an ex- 
plicit declaration for P exists. Pointer 
variables can be declared explicitly, with 
the following format: 

identifier POINTER 

when an unqualified reference is made to 
the based variable, the value of the point- 
er variable included in the declaration 
will be used to determine which allocation 
is concerned. For example: 

X = X ♦ 1; 

In this statement, the pointer variable 
used to determine the location of X will in 
both cases be P; that is, the references to 
X are implicitly qualified by the pointer 
P. Note, however, that X could have been 
explicitly qualified by other pointer 
variables. Explicit pointer qualification 
is discussed below. 



POINTER QUALIFICATION 

Reference to a based variable can be 
explicitly qualified by means of the fol- 
lowing format: 

pointer-variable -> based-variable 

The pointer variable must be neither 
subscripted nor based; a qualified name is 
allowed. For example: 

P -> X = Q -> X; 

This statement means simply that the value 
of one allocation of X is to be assigned to 
another allocation of X; the X allocated in 
the location associated with P is to be 



RULES AND RESTRICTIONS 

Full details of the rules governing 
based variables and pointer variables are 
given under the respective attributes in 
Section I, Attributes. However, the fol- 
lowing points should be carefully noted: 

1. Based variables may not have the 
EXTERNAL, VARYING, or INITIAL 
attributes. 

2- The* bounds of based arrays and the 
lengths of based strings must be 
declared using decimal integer con- 
stants, with the exception that the 
REFER option (see "The REFER Option" 
in this section) allows, one adjustable 
array bound, string length, or area 
size to be declared within a based 
structure. 

3. Based label arrays cannot be initial- 
ized by subscripted label prefixes. 

<*. Based variables cannot be checked by 
means of a CHECK condition prefix. 

5. Based variables cannot be transmitted 
using data-directed input/output. 

6. The pointer variable qualifying a 
based variable (whether implicitly or 
explicitly) cannot itself be based, 
nor can it be subscripted; it must be 
an element variable, or an element of . 
a structure; a qualified name is 
allowed. (Arrays of pointer variables 
are allowed, but the value of an ele- 
ment of such an array would have to be 
assigned to an element pointer vari- 
able before it could be used to quali- 
fy a based reference. ) 

7. Pointer variables cannot be operands 
of any operators except the comparison 
operators = and ^=. The value of a 
pointer variable can be compared with 
that of any other locator variable, or 
with a locator value returned by a 
function. 
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8, Assignment of a pointer variable value 
can be made only to another locator 
variable. 

9. Pointer variables cannot be trans- 
mitted using STREAM input/output. 

10. The pointer variable declared with a 
based variable is not given the value 
of the NULL built-in function by the 

declaration, 

11. Only the INITIAL CAUL form of the INI- 
TIAL attribute is allowed in pointer 

declarations . 

12. The implementation of offsets and 

pointers does not support bit addres- 
sing. This restriction has no practi- 
cal effect on ALIGNED bit strings. 
With UNALIGNED bit strings belonging 
to arrays or structures, however, only 
offsets or pointers to major struc- 
tures or minor structures with byte 
Cox higher) alignment should be used. 

Note : The allocation of a based variable 
will always take at least eight bytes of 
storage, even if the based variable is a 
bit- string variable of length 1. 

P ointer Defining 

A pointer variable can be defined on 
another pointer variable using overlay or 
correspondence defining. 



SELF-DEFINING DATA 

A self -def ining record is one which con- 
tains, within itself, information about its 
own fields, such as the length of a string. 
PL/I allows the user to declare a based 
structure in a way that is designed to help 
manipulate such data. A based structure 
can be declared to have either one adjust- 
able array bound, one adjustable string 
length, or adjustable area size f governed 
by a variable contained within the struc- 
ture itself. This variable is given a 
value when the structure is allocated; the 
value is assigned from a variable outside 
the structure. Note that the variable out- 
side the structure is used only on alloca- 
tion (either by an ALLOCATE statement or by 
a LOCATE statement); for any other 
reference to the structure (such as READ 
with SET, discussed later in this section) , 
the variable inside the structure will 
apply. 

The REFER Option 

The REFER option is used in the Jeclara- 
tion of a based structure to specify that, 
on allocation of the structure, the value 
of a variable outside the structure is to 



be assigned to an element of the structure, 
and that this value will be the length, 
size, or bound of another element of the 

same alloca t ion of the structure. 

The REFER option has the following gen- 
eral form: 

element-variable REFER (element-variable) 

The element variables must be unsubscripted 
fixed binary integer variables, and can be 
fullword or half word, but must have the 
same precision. The variable on the left- 
hand side of the keyword must not belong to 
the structure; it can be qualified or 
pointer-qualified. The variable on the 
right-hand side must belong to the 
structure. 

For example; 

DCL 1 STR BASED (P) , 

2 Y FIXED BINARY, 

2 Z (B.X REFER (Y) ) ; 

This declaration specifies that the based 
structure STR will consist of an array Z 
and an element Y; when STR is allocated, 
the upper bound of Z is set equal to the 
current value of B.X r and this value is 
assigned to Y. For any other reference to 
the variable, the bound value is taken from 
Y. 

Note that this option can be used only 
once in a declaration. If it is used to 

specify an array bound, the bound must be 

the upper bound of the leading dimension of 
the element with which it is used, and the 
dimension must belong to the last element 
in the structure declaration, or to a minor 
structure containing the last element. 



For example: 

DCL 1 STR BASED CP) , 
2 A, 

^ B FIXED BINARY, 

3 C (20), 

2 D, 

3 B FIXED BINARY, 

| 3 C (0:X REFER CD.B), 0:9); 

In this declaration, the REFER option is 
used to specify an adjustable upper bound 
for the array D. C; in this cas; f it could 
not have appeared in any place other than 
that shown. Note that even though the rule 
states that the variable on the right-hand 
side of the REFER keyword must belong to 
the structure containing the REFER option, 
this variable must still be sufficiently 
qualified to avoid ambiguity with members 
of other structures. In this case, a 
reference to B alone would not be suffi- 
cient, since structure A also contains a 
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member named B. This would apply even if A 
and D were separate major structures. 

Note ; Since the adjustable bound must be 
part of the leading dimension of the ele- 
ment with which it is declared, it is not 
possible for that element to inherit a 
dimension from a higher level. (Inherited 
dimensions would automatically become the 
leading dimensions of the lower-level 
member . ) 



For example: 



DCL 



1 STR BASED (P) , 
2 C (10) , 

3 E (50), 
3 F (50); 



In this declaration, both E and F would 
have implied bounds of 1:10, inherited from 
D; the REFER option could not have been 
used with them but could have teen used 
with D (in place of 10). 

If the REFER option is used to specify a 
string length, that string must be an ele- 
ment variable, and it must be the last ele- 
ment variable in the structure declaration. 

If the element variable on the right- 
hand side of REFER varies during the pro- 
gram then: 

1. The structure must not be freed until 
the element variable is restored to 
the value it had when allocated; 

2. The structure must not be written out 
while the element variable has a value 
greater than the value with which it 
was allocated. 



to free REC at this point, since N must be 
restored to the value it had when allocated 
(i.e., 100). If N was assigned a value 
greater than 100, an error would cccur when 
the WRITE statement was encountered. 

POINTER SETTING, BASED STORAGE ALLOCATION, 
AND INPUT/OUTPUT 

Before a reference can be made tc a 
based variable, the qualifying pointer 
variable must have a value. This value can 
fce set in any of five different ways: 

1. With the SET option of a READ 
statement; 

2. By a LOCATE statement; 

3. By an ALLOCATE statement; 

4. By assignment of the value of another 
locator variable, or a locator value 
returned ty a user-defined function; 

5. By assignment of an ADDR built-in 
function value. 

Note that the actual value is in all 
cases set ty the compiler. The user has no 
direct control over addressing; he cannot, 
for example, assign a constant to a pointer 
variable. 

A special fcrm of assignment tc a point- 
er variable is made using the NULL built-in 
function. This assigns a special value tc 
the pointer, that cannot be related to any 
address; its purpose is to give a positive 
indication that the pointer does not cur- 
rently identify any allocation of a 
variable. 



The structure may be written out when 
the element variable has a value equal 
to or less than the value it had when 
allocated. The number of elements or 
the string length actually written 
will be that indicated by the current 
value of the variable. 



For example: 



DCL 1 REC BASED (P) f 
2 N f 

2 A (M REFER(N)), 
M INITIAL (100) ; 



ALLOCATE REC; 

N = 86; 

WRITE FILE (X) FROfc (REC); 

In this example, 86 elements of REC are 
written. It would be an error to attempt 



READ WITH SET 

The READ statement with the SET option 
has the following basic format: 

READ FILE (file-name) 
SET (pointer-variable) ; 

The pointer variable can be any variable 
that represents a single pointer value. 
This form of the READ statement causes a 
record to be read into a buffer and the 
specified pointer variable to be set to 
point to the buffer. A based variable 
reference, qualified by the same pointer, 
will then relate to the fields cf the 
record. 

A based variable used to describe a 
record in a buffer is effectively overlaid 
on the buffer. The result of a reference 
to an element cf the based variable is the 
same as it would be if the record had been 
read directly into the structure described. 
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If the REFER option is used in the 
declaration of a structure, and the pointer 
to the structure is set by a READ statement 
with the SET option, the value for the 
appropriate array bound, string length, or 
area size is taken from the variable inside 
the structure (i.e., from the record 
itself) , not from the variable outside the 
structure. For example: 



DCL 



1 REC BASED (P) , 
2 N, 

2 ACM REFER (N) ) , 
M INITIAL(IOO) , 
INFILE FILE RECORD; 
ALLOCATE REC; 



FREE REC; 



READ FILE(INFILE) SET(P); 



In this example, when REC is first allo- 
cated, the array A has 100 elements and N 
has the value 100. On execution of the 
READ statement, however, the number of ele- 
ments in the array is specified in that 
part of the record effectively overlaid by 
N; the value of M has no effect. 



LOCATE WITH AND WITHOUT SET 

The LOCATE statement has the following 
basic format: 

LOCATE based-variable FILE (file-name) 
(SET (pointer-variable) ] ; 

The pointer variable can be any variable 
that represents a single pointer value. 

This statement allocates storage, in an 
output buffer, for a based variable. The 
action is similar to that of the READ and 
SET, in that the based variable is, in 
effect, overlaid on the buffer. In this 
case, however, data is moved (by subsequent 
statements) into the output buffer in such 
a way that the fields of the record are 
located relative to the elements of the 
based variable; the record is automatically 
written onto the specified file immediately 
before execution of the next WRITE, LOCATE, 
or CLOSE statement (or implicit close 
operation) for the file. This means that 
the user must assign values to the variable 
after allocation and before the next input/ 
output operation on the file. 

Again, a pointer variable is set to 
point to the buffer. This pointer variable 
will be that specified in the SET option, 
if the option appears; if the option is 
omitted, the pointer variable that *ias 



declared with the specified based variable 
is set. 



ALLOCATE WITH AND WITHOUT SET 

The ALLOCATE statement, as used with 
based variables, has the following basic 
format : 

ALLOCATE based-variable 1 IN (area- variable) ] 
[SET(pcinter-variafcle) J; 

The effect of this statement is similar 
to that of the LOCATE statement, in that it 
allocates storage for the based variable 
and sets a pointer to point to the alloca- 
tion. In this case, however , no output is 
implied; the storage is not allocated in a 
buffer. If the SET option appears, the 
specified pointer variable is set; if the 
option is omitted, the pointer variable 
that was declared with the specified based 
variable is set. 

The IN option, if included, specifies 
that the allocation is to be made within 
the reserved area of storage named. Areas 
are discussed in detai 1 later in this 
chapter. The area variable can be any 
variable that represents a single area; the 
pointer variable can be any variable that 
represents a single pointer value. 



POINTER ASSIGNMENT 

The value of a pointer variable may be 
assigned to another pointer variable in a 
simple assignment statement. Assune that P 
and Q are pointer variables and that P has 
a valid pointer value. 
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The ADDR Built-in Function 

The value returned by the ADDR built-in 
function is a valid pointer value that spe- 
cifies the location of a data variable 
named as the argument of the function 
reference. For example: 

P = ADDR (X) ; 

Execution of this statement will give 
the pointer variable P a value so that it 
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points to the location of the data variable 
x. The value of an ADDR function reference 
can be assigned to a locator variable only. 

The argument can be a variable that 
represents an element, an array, a struc- 
ture, an area, an element of an array, a 
minor structure, or an element of a struc- 
ture. The value returned is always a 
pointer value. Note that if a based vari- 
able has not been allocated* its ADDR is 
undefined; however r the ADDR value of an 
unallocated controlled variable is null. 

The ADDR of an element of an array or 
structure returns a value that relates to 
the address of the element . However, a 
pointer qualifying a subscripted or quali- 
fied variable is assumed to point to the 
array or structure in which the element is 
contained, not to the element itself- For 
example: 

DCL A (10,10) CHARACTER (20) BASED (P) , 
B CHARACTER C20) BASED (Q) , 
C CIO, 10) CHARACTER C20); 

Given this declaration, if ADDR CO* is 
assigned to P, then A (1,1) will refer to 
the first element of C. If ADDR (CC2,3)) 
is assigned to Q t then B is effectively 
overlaid on the third element in the second 
row of c. • (This technique, like the other 
overlaying techniques made possible by the 
use of based variables and pointers, is 
extremely powerful; however, such tech- 
niques should be used only with the under- 
standing that the compiler has no means of 
recognizing incompatibilities between the 
attributes of the based variable and the 
attributes of the variable being effective- 
ly overlaid. ) 

Since ADDR returns a single value only, 
the elements of an array or structure argu- 
ment must occupy successive locations in 
storage. For example: 

DCL A(10, 10} ; 

For the array, declared above, ADDR would 
not be permitted for the cross-section 
AA(*,10), because each element in the cross- 
section would belong to a different row, 
and would be separated from its column 
neighbor by other elements in its row. 
ADDR would, however, be permitted for the 
cross-section A(10,*); this cross-section 
consists of one entire row whose elements 
occupy successive locations in stcrage. 

Note also that since the TSS/360 PL/I 
compiler does not support based-st jrage bit 
addressing, the argument to th* 3 ADDR built- 
in function must be aligned on a byte (or 
higher) boundary. In the case of bit 
strings belonging to unaligned arrays and 
structures, therefore, ADDR should be used 
only for the level 1 name or for minor 



structures that are not composed entirely 
of bit strings. 

The NULL Built-in Function 

The NULL built-in function requires no 
arguments; it returns a null pointer value 
(that is, a special pointer value that can- 
not relate to any address in storage) . Its 
purpose is to provide a positive indication 
that a pointer does not currently identify 
any allocation of a variable. Examples of 
its use include the following; 

1. If NULL is assigned to a pointer at 
the start of a program, a later test 
of the pointer against NULL will show 
whether a based variable qualified by 
the pointer has been allocated or not. 

2. A terminal pointer in a chain can be 
set to the value of NULL so that the 
beginning or end of the chain can be 
recognized. 



FREEING BASED STORAGE 

The storage that has been associated 
with a based variable by one of the alloca- 
tion methods described above can be freed 
explicitly or, in certain cases, implicit- 
ly, for possible reuse- Once the storage 
for a based variable has been freed, a 
reference to the associated pointer becomes 
invalid. 



THE FREE STATEMENT 

The FREE statement, as applied to based 
variables, has the following basic format: 

FREE qualified-reference 
[IN (area-variable) ] 
C , qualif iedh reference 
UN f area -variable) ] J . * . ; 

where "qualified-reference" is defined as: 

[pointer-variable ->] based-variable 

This statement frees the storage asso- 
ciated with one or more allocations of one 
or more specified based variables, The 
allocations are identified by the current 
values of the specified pointers. If a 
pointer is omitted, it is assumed to be 
that declared with the based variable 
concerned. 

IN (area-variable) must be specified if 
the allocation was made within an area; 
otherwise, It must be omitted. Areas are 
discussed later in this section. 

The amount of storage freed depends on 
the attributes of the based variable, 
including the current value of any ad just- 
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able bound or length specification- The 
user is responsible for ensuring that the 
amount freed coincides with the amount 
originally allocated. For example: 

DECLARE 1 S BASED (P) , 

2 N, 

2 XCM REFER <N)> ; 



conversion to offset? similarly, assignment 
from offset to pointer implies conversion 

to pointer* Hence f an offset variable can 
be given a value by assigning a pointer 
value to it; and, in order to use an offset 

as a qualifier* its value is assigned to a 
nonbased pointer . 



M = 50; 

ALLOCATE S; 

/*X HAS 50 ELEMENTS AND THE VALUE OF N IS 

SET TO 50*/ 



M = 80; /*THIS HAS MO EFFECT ON THE CUR- 
RENT ALLOCATION OF S*/ 
P -> N = 10; 

FREE S; 

/♦THIS IS IN ERROR BECAUSE STORAGE EQUIV- 
ALENT TO 40 ELEMENTS OF X IS LEFT 

UNFREED*/ 

It is an error to attempt to free based 
variables that have not been allocated. 



IMPLICIT FREEING 

In certain circumstances, based storage 
is freed without the use of an explicit 
FREE statement, as follows: 

1. Storage that has been' allocated by the 

LOCATE statement is freed after the 

variable is written out. 

2. Storage that has been effectively 
allocated by a READ statement with the 
SET option is freed by the next read 
or close operation on the file. 



AREAS AND OFFSETS 

Based variables can be allocated within 
an area of storage that has been reserved 
by allocation of an area variable. This 
has the effect of grouping the data items 
together so that they can be easily trans- 
mitted or assigned as a single unit while 
still retaining their individual identi- 
ties. The items stay in their relative 
locations, which can be identified by. of f- 
sets from a pointer that identifies the 
start of the area. This does not mean that 
pointers cannot be used within areas; 
however, offsets have the advantage of 
remaining valid during area transmission 
and assignment. 

Offsets, like pointers, can be ustd to 
build chains of data; however, they cannot 
be used directly as based variable quali- 
fiers nor can they appear in a SET option. 
Assignment from pointer to offset implies 



AREA VARIABLES 

The AREA attribute defines an area of 
storage that is to be reserved for the 

allocation of based variables. It has the 
following general format: 

AREA [(size)] 

Note : The size can be an expression or an 
asterisk. 

The number of bytes of storage is speci- 
fied by an asterisk or by the integral 
value of the expression, if present; other- 
wise, an implementation defined value of 
1000 bytes is assumed. This value is the 
size of the area. 

The implementation defined maximum size 
of an area is 32,767 bytes. 

Tne size of an area is the amount of 
storage that is reserved by the area allo- 
cation for the allocation of based 
variables. The amount of the reserved 
storage that is actually in use is known as 
tne extent of the area; it is defined as 
the amount of storage between the start of 
the reserved area and the end of that 
unfreed allocation which is furthest from 
the start of the area. In addition to the 
declared size r the implementation requires 
an extra 16 bytes of control information, 
giving such details as the size, and the 
length of the current extent. These 16 
bytes are allocated immediately before the 
start of the reserved area, and are added 
to the area size to obtain the length of 
the area, i.e., the actual amount of , 
storage needed for the area allocation. 
The distinction between area size and 
length is important to the discussion of 
area I/O later in this section. 

Examp le : 

DECLARE A STATIC AREAC2000), 
B AREA, 
C AREA CN) ; 

This statement specifies that: 

1. A is a static area variable reserving 
2000 bytes of storage. IThe size of 
an area of static storage class, if 
specified, must be specified as an 
unsigned fixed decimal integer 
constant. ) 
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3. 



B is an automatic area variable 
reserving 1000 bytes of storage. 

C is an automatic area variable whose 
size depends on the value of N current 
at the time of entry to the block. 



Rules and Restrictions 

The following rules apply to area 
variables : 

1. Data of the area type cannot be con- 
verted to any other data type; an area 
can be assigned to an area variable 
only. 

2. No operators can be applied to area 
variables. 

3. Only the INITIAL CALL form of the INI- 
TIAL attribute is allowed with area 
variables. 

4. When an area is allocated, it is auto- 
matically given the EMPTY state (see 
•The EMPTY Built-in Function" in this 
section, for explanation of EMPTY). 

5. An asterisk can be used to specify the 
size if the area variable being 
declared is controlled or is a para- 
meter- In the case of a controlled 
area variable where size is declared 
with an asterisk, the size must be 
specified in the ALLOCATE statement 
used to allocate the area. In the 
case of a parameter declared with an 
asterisk, the size is inherited from 
the argument. 



OFFSET VARIABLES 



This declaration specifies that A is a 
based area variable, that the value of O 
will point to a location relative to the 
start of A, and that X is a based variable. 
If X were now allocated within A, the v^lue 
of its pointer could be assigned to O to 
establish the location of X relative to the 
start of A. If A and O were written out 
and then read back in again, O would still 
point to X relative to the start of A, 
although the pointer for A itself would 
have been reset. 

Rules and Restrictions 

The following rules apply to offset 
variables: 

1. Offset variables cannot be used to 
qualify a based reference. 

2. Assignment of an offset value can be 
made only to a locator variable. When 
an offset value is assigned to an off- 
set variable, the area variables named 
in the OFFSET attributes are ignored. 
A pointer value can be assigned to an 
offset variable, with implicit 
conversion. 

3. Offset variables cannot be operands of 

any operators except the comparison 
operators = and 1 =. The value of an 
offset variable can be compared with 
that of any other locator variable, or 
with a locator value returned by any 
function. 

4. Offset variables cannot be transmitted 
using STREAM input /output. 

5. Offset variables cannot appear in any 
SET option. 



Declaration of an offset variable must 
be explicit. The OFFSET attribute has the 
following form: 

OFFSET (variable) 

The variable within the parentheses must 
be an unsubscripted level 1 based area 
variable. 

The function of an offset variable is to 
provide a locator value that points to the 
location of a based variable relative to 
the start of a based area. If the contain- 
ing area is transmitted or assigned, the 
offsets will still point to the correct 
locations of the components. 

Example : 

DECLARE A AREA BASED(P>, 
O OFFSET (A) , 
X BASED(Q); 



ALLOCATION WITHIN AN AREA 

Based variables are allocated within an 
area try means of an ALLOCATE statement with 

the IN option. This sets a pointer which 
can he converted to offset by assignment to 

an offset variable. For example; 

DECLARE A AREA BASEDCV), 
1 B BASED(P), 
2 O OFFSET (A) , 
2 VALUE, 
Q POINTERS- 
ALLOCATE A; 



ALLOCATE B IN (A) ; 



ALLOCATE B IN (A) SET (Q) ; 
0=Q; 



Section 14: Based Variables and List Processing 145 



Page of GC28-2045-1, issued September 15, 1970 by TNL GN28-3171 



The first ALLOCATE statement causes the 
area A to be allocated* reserving 1000 
bytes of storage for allocation of based 

variables, and sets V. 

The second ALLOCATE statement causes B 

to be allocated within the area V ~> A, and 

sets P. 

The third ALLOCATE statement causes 
another allocation of B (different from P* 
-> B> to be made within the area V ~> A f 

and sets Q. 

The assignment statement causes the 
value of Q to be converted to offset (rela- 
tive to the pointer V) and assigned to P - 
> O. Thus* the first allocation of the 
structure B contains an offset value that 
points to the second allocation of B. The 
setting of offset values is discussed 
below. 



SETTING OFFSET VALUES 

An offset variable can be given a value 
by assignment only, since it cannot appear 
in a SET option, nor is any implicit set- 
ting possible . In the above example, P - 
> O was given its value by assignment from 
Q. Note, however, that the reference O -> 
VALUE, for example, would be invalid, since 
offsets cannot be used as qualifiers- 

The NULLO Built-in Function 

The NULLO built-in function is the off- 
set equivalent of the NULL built-in func- 
tion as used with pointers. It requires no 
arguments, and returns a null value that 
can be assigned to offset variables only. 

Notes A null offset value cannot be con- 
verted to a null pointer value, nor can a 
null pointer value be converted to a null 

offset value. Therefore, the value of the 
NULLO built-in function cannot be assigned, 
even indirectly, to a pointer variable; nor 
can the value of the NULL built-in function 
be assigned to an offset variable. For 
example ; 

DECLARE OFFSET CA) , 
P POINTER; 



IF P-NULL THEN 0= NULLO ; 
ELSE 0=P; 



AREA ASSIGNMENT AND INPUT/OUTPUT 

The value of an area expression can be 
assigned to one or more area variables by 
an assignment statement. Area-to-area 
assignment has the effect of freeing all 
allocations in the target area and then 
assigning the extent of the source area to 
the target area, in such a way that all 
allocations in the source area maintain 
their locations relative to each other; 
that is, any gaps left by freeing opera- 
tions in the source area are maintained 
during the assignment Csuch a gap might 
have been left, for example, if the second 
of three contiguous allocations had been 
freed; if the gaps were automatically 
closed up, some offset values might lose 
their meaning) • 

If a source area containing no alloca- 
tions is assigned to a target area, the 
effect is merely to free all allocations in 
the target area* 

A possible use for area assignment is to 
allow for expansion of a list of based 
variables beyond the bounds of its original 
area- When an attempt is made to allocate 

a based variable within an area that con- 
tains insufficient free storage to accom- 
modate it, the AREA condition is raised 
(see below). The on-unit for this condi- 
tion could be to change the value of a 
pointer qualifying the reference to the 
inadequate area, so that it pointed to a 
different area; on return from the on-unit, 
the allocation would be attempted again, 
within the new area. Alternatively, the 
on-unit could write out the area and reset 
it to EMPTY, 

The EMPTY Built-in Function 

The EMPTY built-in function requires no 
arguments and returns an area of zero size 

and extent. The effect is to free all 
allocation in the target area. 

Examp le : 

DECLARE A AREA, 

I BASEDCP), 
J BASED (Q) ; 



P=NULL; 

0=P; 

0= NULLO; 

P=0; 

The second and fourth assignments in the 
above example would be invalid. They could 
be made valid by inserting IF statements, 
such as the following* 



ALLOCATE I IN(A) ff J IN (A) ; 



A=EMPTY; 

/♦EQUIVALENT TO: 

FREE I IN (A) f J IN 



CA) ; */ 
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The AREA ON- Condition 

The AREA condition is raised in any of 
the following circumstances: 

1. When an attempt is made to allocate a 
based variable within an area that 
contains insufficient free storage for 
the allocation to be made, 

2. When an attempt is made to perform an 
area assignment, and the target area 
contains insufficient storage to 
accomodate the extent of the source 
area. 

3. When a SIGNAL AREA statement is 
executed. 

The ONCODE built-in function can be used 
to determine whether the condition was 
raised by an allocation, an assignment, or 
a SIGNAL statement. 

On normal return from the on- unit, the 
action is as follows: 

1. If the condition was raised by an 
allocation, the allocation is re- 
attempted. If the on-unit has changed 
the value of a pointer qualifying the 
reference to the inadequate area so 
that it points to another area, the 
allocation is reattempted within the 
new area. Note that if the on-unit 
does not effectively correct the 
fault, a loop may result. 

2. If the condition was raised by an area 
assignment, or by a SIGNAL statement, 
execution continues at the point of 
interruption . 

If no on-unit is specified, the system 
will comment and raise the ERROR condition. 

Input and Output 

The area facility is designed to allow 
easy input and output of complete lists of 
based variables as one unit, to and from 
RECORD files. The control information is 
transmitted with the area. Consequently, 
the record length required is governed by 
the area length (i.e., area size * 16): 
the RECORD condition is raised if the 
length of an area named in the INTO option 
of a READ statement, or in the FROM option 
of a WRITE statement, differs from the 
relevant record length. Note that even 
though the RECORD condition is raised, 
incorrect control information will be 
transmitted; when an area is written out, 
it must not be read back into an area of 
different size- 
In the case of READ with SET, the length 
of the input area in the buffer is equal to 



the length of the area used to create the 

record. 



AREA AND OFFSET DEFINING 

An offset can be defined on an offset, 
using overlay or correspondence defining. 
In the declarations of the defined offset 
and the base offset, the variables named in 
the two OFFSET a tt tributes need not be the 
same. 

Similarly, an area can be defined on an 
area, using overlay or correspondence 
defining. The base area must have a size 
equal to that of the defined area. 



C OMMUNICATION BETWEEN PROCEDURES 

Similarly to variables of other data 
types, locator and area variables in one 
procedure can be related to those in anoth- 
er procedure by means of arguments and 
parameters, and the general rules are as 
described in Part I, Section 12, "Subrou- 
tines and Functions." There are necessari- 
ly some restrictions, which will be 
explained in the following discussion; but 
a general rule is that where it is possible 
to assign the value of one variable to 
another variable, it is also possible to 
relate the two variables by an argument and 
a parameter. 



ARGUMENTS AND PARAMETERS 

A locator argument of either pointer or 
offset type can be passed to a locator pa- 
rameter cnly. The parameter can be of 
either type, but if the argument type dif- 
fers from the parameter type, a dummy argu- 
ment is created by the compiler, and a 
change in the value of the parameter will 
not be reflected in the value of the origi- 
nal argument. 

Pointer to Pointer 

No conversion is necessary when a point- 
er argument is passed to a pointer parame- 
ter; normally, therefore, no dummy argument 
is created, and a change in the value of 
the parameter will be reflected in the 
value of the argument. Note, however, that 
this reflected change could be avoided, if 
necessary, by passing the argument as an 
expression in parentheses: this causes a 
dummy argument to be created. For example: 

PRCC1: PROCEDURE; 

DECLARE (P,Q) POINTER; 



CALL PROC2UP) ,Q) ; 
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PROC2: PROCEDURE (R,S> ; 

DECLARE (R,S) POINTER? 



END PROC1; 

In this example, a change in the value 
of S will be reflected in the value of Q, 
tut a change in the value of R will have no 
effect on P. 

Offset to Pointer 

Passing an offset argument to a pointer 
parameter implies conversion to a dummy 
pointer argument, which is then passed to 
the entry point. The entry must be 
declared with the POINTER attribute in the 
parameter attribute list. For example: 

PROC3 : PROCEDURE ; 

DECLARE PR0C4 ENTRY 
(POINTER) , 

O OFFSET ( A) , 

A AREA BASED (P) ; 



CALL PROCMO); 
PROC4 : PROCEDURE (Q) ; 

DECLARE Q POINTER; 



END PROC3; 

In this example, the values of P and 
are used to obtain the value of the dummy 
pointer argument to be passed to PROC4. 

Offset to Offset 

When an offset argument is passed to an 
offset parameter, variables named in the 
OFFSET attribute of the offset declarations 
are ignored, just as they are ignored for 
offset assignment; if they differ, the fact 
that they differ does not imply conversion 
to a dummy argument. For example: 

PROC5: PROCEDURE? 

DECLARE OA OFFSET (A), 

A AREA BASED (P) , 

B AREA BASED (Q), .-. 



CALL PROC6COA) ; 
PR0C6 : PROCEDURE (OB) ; 

DECLARE OB OFFSET (B) , • 



END PROC5; 

In this example, OA would be passed 
directly to OB. 



Pointer to Offset 

Passing a pointer argument to an offset 
parameter implies conversion to a dummy 
offset argument, which is then passed to 

the entry point. The entry must be 
declared with the OFFSET attribute in the 
parameter attribute list, and the two OFF- 
SET attribute specifications must name the 
same variable. For example: 

PR0C7 : PROCEDURE ; 

DECLARE PR0C8 ENTRY (OFFSET (A)}, 

P POINTER, 

A AREA BASED (Q) ; 



CALL PROC8 (P) ; 
PROC8 : PROCEDURE (0) ; 

DECLARE O OFFSET (A) ; 



END PROC7; 

In this example, the values of P and Q 
are used to obtain the value of the dummy 
offset argument to be passed to PR0C8. 

The variable following the keyword OFF- 
SET is not considered during selection of a 
generic entry point. 

Area to Area 

An area argument can be passed only to 
an area parameter. If the size of the 
argument differs from the size appearing in 
the parameter attribute list of the rele- 
vant entry declaration, the argument is 
first assigned to a dummy area argument 
with the size specified in the entry 
declaration; the dummy argument is then 
passed tc the entry point. 

The size of an area argument is not con- 
sidered during selection of a generic entry 
point. 



RETURNS FROM ENTRY POINTS 

An entry point can return a locator 
value or an area; hence, the PROCEDURE and 
ENTRY statements and the RETURNS attribute 
iray specify the POINTER, OFFSET, or AREA 
attributes. 

locator Returns 

Either type of locator variable can 
appear in a RETURN statement in a procedure 
that returns a locator value. If the pro- 
cedure is to return an offset value but the 
RETURN statement specifies a pointer, there 
is implicit conversion to offset, and vice 
versa. For example: 
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PROCA: PROCEDURE POINTER; 

DECLARE A AREA BASED (P) , 
O OFFSET (A) ; 



RETURN CO; 
END PROCA; 

The values of O and P are used to obtain 
the pointer value to be returned • 

PROCB: PROCEDURE OFFSET (B); 

DECLARE B AREA BASED CQ) , 
R POINTER; 



RETURN (R); 
END PROCB; 

The values of Q and R are used to obtain 
the offset value to be returned. Note that 
the OFFSET attribute is specified in the 
PROCEDURE statement complete with the nam,e 
of the relevant area variable; the keyword 
OFFSET alone is not sufficient. 

Similarly, a locator value returned by a 
function may undergo implicit conversion. 
For example: 

DECLARE O ENTRY RETURNS ( OFFSET ( A)) , 
A AREA BASED (P) , 
Q POINTER; 



Q=0; 

The value cf P and the value returned by 
are used to obtain the pointer value to 
be assigned to Q. 

Area Returns 

If a return statement identifies an area 
that has an extent different from that 
specified in the relevant PROCEDURE or 
ENTRY statement, assignment is made to a 
dummy area with the correct extent, thus 
effectively performing a conversion. 



VARIABLE LENGTH PARAMETER LISTS 

In PL/ I, a procedure can have only a 
fixed number of parameters, all of which 
must be specified. However, by passing an 
array of pointers as a single argument, it 
is possible to simulate a variable length 
parameter list, since the array can have 
adjustable bounds. 

The following procedure sorts a variable 
number of based character-strir* j variables 
according to their values in relation to 
the collating sequence. The pointers qual- 



ifying these based variables are passed as 
an array argument to the procedure. 



Assume that the calling procedure con- 
tains an array of pointers, KEYPOINTS, with 
one dimension, which is named as an argu- 
ment in the CALL statement, and whose ele- 
ments each point to a based character- 
string variable. 



SORT : PROCEDURE (P) ; 
DECLARE 

PC*) POINTER, 
CH,L) FIXED BINARY, 
LISTEL BASED CP0INTER1) 
CHARACTER C60), 
POINTER 2 POINTER; 



H=HB0UNDCP # 1) ; 
L=LB0UNDCP,1> ; 

/*THE HBOUND AND LBOUND BUILT-IN 
FUNCTIONS RETURN THE UPPER AND 
LOWER BOUNDS OF THE SPECIFIED 
DIMENSION CIN THIS CASE, THE FIRST 
AND ONLY DIMENSION). THESE VALUES 
ARE USED IN SETTING THE CONTROL 
VARIABLES OF THE FOLLOWING 
DO-GROUPS SO THAT THE NUMBER OF 
ITERATIONS IS CORRECT FOR THE 
NUMBER OF PARAMETERS*/ 

II: DO I=L TO H-l; 

P0INTER1=P(I); 

/*THE VARIABLE LISTEL NOW HAS A 

VALUE*/ 

DO J=I+1 TO H; 
POINTER2=PCJ) ; 

/*THIS IS NECESSARY, SINCE THE 
IMPLEMENTATION DOES NOT 
SUPPORT SUBSCRIPTED POINTER 
QUALIFIERS*/ 

IF LISTEL /* IMPLICITLY QUALIFIED 
BY POINTER1*/ 
>P0INTER2->LISTEL 
THEN DO; 
/♦REORDER ARRAY ELEMENTS*/ 
P(I)=P(J); 
PCJ)=POINTERl; 
P0INTER1=PCI); 

END 111 
END SORT; 

After execution of this procedure, the 
elements of KEYPOINTS will have been rear- 
ranged so that the first element points to 
the based variable with the lowest value 
according to the collating sequence, the 
second element points to the based variable 
with the next lowest value, and so on. 
Thus, the based variables will have been 
logically sorted without changing the phys- 
ical order of the data. 
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EXAMPLES OF LIST PROCESSING TECHNIQ UE 

The following examples illustrate the 
use of based storage, locator variables, 
and areas, for list processing and 
input/output . 



Example 1 

This procedure builds a two-directional 
chain through items that are allocated in 
the calling procedure and identified in 
turn by passing a pointer parameter. Each 
item consists of an allocation of a basic 
structure that contains two pointers and a 
data value (in this case, a character 
string). One pointer identifies the pre- 
ceding item, and the other identifies the 
following item. The ends of the chain are 
recognized by a null value for a contained 
pointer (for example, the backwards pointer 
in the first item is null). The locations 
of the ends of the chain are identified by 
a head pointer and a tail pointer. Figure 
19 shows a diagrammatic representation of 
the chain. 

/♦EXAMPLE 1*/ 

BUILD_CHAIN: PROCEDURE ( ELEMPTR) ; 
DECLARE 

1 ELEMENT BASED (ELEMPTR) , 

2 BACK_CHAIN POINTER, 
2 FWD_CHAIN POINTER, 
2 DATA CHARACTER ( 50 ) , 
ELEMPTR POINTER, 
(HEAD, TAIL) POINTER STATIC EXTERNAL; 



/♦ASSUME THAT HEAD AND TAIL ARE 
INITIALLY ASSIGNED THE VALUE OF THE 
NULL BUILT-IN FUNCTION IN THE PROCEDURE 
THAT CALLS BUILD_CBAIN*/ 

IF HEAD=NULL 

THEN /*FIRST ELEMENT*/ 

HEAD=ELEMPTR; /*SET HEAD POINTER*/ 

ELSE /*NGT FIRST ELEMENT*/ 
TAIL->FWD_CHAIN=ELEMPTR ; 
/♦UPDATE FWD CHAIN*/ 

BACK_CHAIN=TAIL; 
/♦UPDATE BACK CHAINS/ 

TAIL=ELEMPTR; /^UPDATE TAIL POINTER^/ 

FWD_CHAIN=NULL; /+SET END INDICATOR OF 

FWD CHAIN+/ 

END BUILD_CHAIN; 

Ncte that the parameter ELEMPTR may 
identify a nonbased structure, provided 
that this structure has the same structur- 
ing and attributes as ELEMENT. 

Example 2 

This procedure deletes an item from the 
chain created fcy the procedure in example 
1. The item to be deleted is identified by 
a pointer parameter. 

/♦ EXAMPLE 2 ♦/ 

ALTER_CHAIN: PROCEDURE ( ELEMPTR) ; 
DECLARE 
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Figure 19. Example of Two-Directional Chain 
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1 ELEMENT BASED (ELEMPTR) , 

2 BACK_CHAIN POINTER, 

2 FWD__CHAIN POINTER, 

2 DATA CHARACTER C 50) f 
ELEMPTR POINTER, 

(HEAD, TAIL) POINTER STATIC EXTERNAL, 
(PRED, SUCC) POINTER STATIC; 

/♦SET POINTERS TO PREDECESSOR AND 

SUCCESSOR OF ELEMENT BEING DELETED. 
PRED AND SUCC ARE USED BECAUSE 
BACK_CHAIN AND FWD__CHAIN, BEING BASED, 
CANNOT BE USED AS QUALIFIERS*/ 

PRED=BACK_CHAIN ; 
SUCC=FWD_CHAIN ; 

/♦UPDATE FORWARD CHAIN*/ 
IF PRED=NULL 

THEN HEAD=SUCC; /^DELETE HEAD+/ 

ELSE PRED->FWD_CHAIN=SUCC? 

/♦UPDATE BACKWARD CHAIN*/ 

IF SUCC=NULL 

THEN TAIL=PRED; /*DELETE TAIL*/ 
ELSE SUCC->BACK_CHAIN=PRED; 

END ALTER_CHAIN; 

Example 3 

This procedure builds a sequential list 
through several allocations of an area 
variable. Within each area allocation, the 
procedure builds a chain of structure allo- 
cations, each of which contains an offset 
identifying the following item in the 
chain, a character string value, and a 
value (passed from the calling procedure) 
indicating the length of tne string. The 
location of the first iterr in the chain is 
indicated by an offset attached to the 
area. This offset is part of a structure 
containing the first offset and the area; 
consequently, the area is a level 2 vari- 
able. Since a level 2 variable cannot be 
named in the OFFSET attribute, a dummy 
level 1 area variable is effectively over- 
laid on the level 2 area, and this dummy is 
named in the OFFSET attributes. 

The procedure sets pointers to the start 
of the area and to each item in the area. 
These pointers are external, and are there- 
fore known to the calling procedure. 

Each area allocation is in output buffer 
space, and when filled, is written onto a 
data set, using locate-mode output. This 
output process is controlled by an on-unit 
for the AREA condition. The items in the 
area are chained by offsets to ensure that 
the chain is not invalidated by iniut/ 
output operations on the list. It is 
assumed that the output file is opened and 
closed by the calling procedure. 

/♦EXAMPLE 3*/ 

BUILD LIST: PROCEDURE ( N) ; 



DECLARE 

N FIXED BINARY, 
1 LIST BASED (LISTPTR), 
2 FIRST OFFSET (DUMMY) , 
2 BODY AREA, 
1 ELEM BASED (ELEMPTR) , 
2 CHAIN OFFSET ( DUMMY ) , 
2 STRING, 

3 LENGTH FIXED BINARY, 
3 DATA CHARACTER (N REFER 
(LENGTH)), 
(ELEMPTR, LISTPTR) POINTER STATIC 
EXTERNAL, /♦THESE POINTERS ARE 
INITIALIZED TO NULL BY THE CALLING 
PROCEDURE^/ 

LFILE FILE RECORD SEQUENTIAL 
EXTERNAL, 

LASTELEM POINTER STATIC, 
DUMMY AREA BASED (DPTR) ; 

ON AREA 

BEGIN; /♦ALLOCATE OUTPUT BUFFER 
SPACED/ 

LOCATE LIST FILE (LFILE) SET 

(LISTPTR) ; 

DPTR=ADDR(BODY) ; 

LASTELEM=NULL; /♦INDICATES NEW 

AREA*/ 

END; 

IF LISTPTR=NULL 

THEN SIGNAL AREA? /*CREATE FIRST AREA+/ 

ALLOCATE ELEM IN (BODY) ; / ♦ELEMPTR IS 

SET AUTOMATICALLY*/ 

IF LASTELEM=NULL /*SET FORWARD CHAIN*/ 

THEN FIRST=ELEMPTR; /*FIRST ELEMENT 

OF AREA*/ 

ELSE LASTELEM->CHAIN=ELEMPTR; /♦OTHER 

ELEMENTS^/ 
CHAIN=NULLO; /*SET END-OF-CHAIN 
INDICATOR*/ 

LASTELEM=E1EMPTR; /*SAVE POINTER TO NEW 
ELEMENT*/ 
END BUILD_LIST; 

Note that LFILE in examples 3 and 4 
should have a record length of 1020 to 
accommodate the records created by alloca- 
tions of the structure LIST. This is made 
up of 1000 bytes (default size for an area) 
plus 16 bytes of area control information, 
plus 4 bytes for the offset variable FIRST. 

ExampJ e 4 

This procedure sequentially retrieves 
the list items created by the procedure in 
example 3. The procedure sets a pointer to 
the next item in the list, or if the item 
has been retrieved, sets the pointer to 
null. 

/♦EXAMPLE 4*/ 

GET_ELEMENT: PROCEDURE? 

/♦ASSUME THE SAME DECLARATIONS AS IN 

EXAMPLE 3, AND ASSUME THAT LISTPTR IS 

INITIALIZED TO NULL BY THE CALLING 

PROCEDURE^/ 
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ON ENDFILE(LFILE) 
BEGIN; 

ELEMPTR=NULL; /*ALL ELEMENTS 

RETRIEVED*/ 

CLOSE FILE(LFILE) ; 

GO TO EXIT; 
END; 

IF LISTPTR=NULL /*£IRST ELEMENT TEST*/ 
THEN DO; 

OPEN FILE(LFILE) ; 

GO TO READ_AREA; 
END; 

IF LASTELEM->CHAIN=NULLO /*END-OF-AREA 
TEST*/ 

THEN RLAD_AREA: /*READ RECORD INTO 
BUFFER*/ 
DO; 

READ FILE(LFILE) SET (LISTPTR) ; 
DPTR=ADDR(BODY) ; 

ELEMPTR=FIRST; /*SET PTR TO FIRST 
ELEMENT*/ 
END; 
ELSE ELEKPTR-LASTELEN.->CHAIN; /*SET 
POINTER TO FOLLOWING ELEMENT*/ 
LASTELEM=ELEMPTR; /*SAVE POINTER TO NEW 
ELEMENT*/ 
EXIT: END GET ELEMENT; 
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SECTION IS: 



COMPILE-TIME FACILITIES 



INTRODUCTION 

Compile time is generally defined as 
that time during which a user's source pro- 
gram is compiled, or translated, into an 
executable object program. Ordinarily, 
changes to a source program may not be made 
at this time. 



However, with PL/ I, the user does have 
some control over his source program during 
compile time. His source program can con- 
tain special statements (identified by a 
leading %) that can cause parts of the 
source program to be altered in various 
ways : 



Any identifier appearing in the source 
program can be changed. 



If conditional compilation is desired, 
the user can indicate which sections 
of his program are to be compiled. 



3. Strings of text residing in a user 
library or a system library can be 
incorporated into the source program. 

PL/I makes source program alteration at 
compile time possible by a somewhat dif- 
ferent approach to compile time processing. 
Compile time as defined in PL/I has two 
stages: 

1. The Preprocessor Stage — During this 
stage, the user's source program is 
scanned for preprocessor statements , 
special statements that cause the pre- 
processor to alter the text being 
scanned. These statements are consi- 
dered part of the source program, and 
appear freely intermixed with the 
statements and other text of the 
source program. The altered source 
program, resulting from the action of 
the preprocessor statements, then 
serves as input to the second stage. 
Note that the preprocessor stage is 
optional. 

2. The Processor Stage — During this 
stage, the output from the first stage 
is compiled into an executable object 
program . 

This section is concerned with the first 
stage; the actual compilation of a program 
is not discussed. 



PREP ROCESSOR INP UT AND O UTPUT 

The preprocessor interprets prepreressor 
statements and acts upon the source pr. gram 
accordingly. Input to the preproces *cc is 
a sequence of characters that is the user's 
source program. It contains preprccess. r 
statements freely intermixed with the rest 
of the user's source program. Preprocessor 
statements are identified by a leading per- 
cent symbol C % ) and are executed as they 
are encountered by the preprocessor (vitj* 
the exception of preprocessor procedures, 
which must be invoked in order to be 
executed) . One or more blanks may separate 
the percent symbol from the statement. 



while checking the preprocessor state- 
ments for correct format and such, the pre- 
processor also checks the rest of the 
source program text to ensure that there 
are no unmatched comment or character- 
string delimiters. A percent symbol 
appearing within a comment or character 
string is considered to be part of that 
comment or string. This is the extent of 
the checking done at this stage on all text 
other than preprocessor statements. 

Output from the preprocessor consists of 
a new character string called the p repro- 
cessed text , which consists of the altered 
source program and which serves as input to 
the processor stage. Note that preproces- 
sor statements are replaced by blanks in 
the preprocessed text. 



PREPROCESSOR SCAN 

The preprocessor starts its scan of the 
input text at the beginning of the string 
and scans each character sequentially. As 
long as a preprocessor statement is not 
encountered, the characters are placed into 
the preprocessed text in the same crder and 
general form in which they were scanned. 
However, when a preprocessor statement is 
encountered, it is executed. This execu- 
tion can cause the scanning of the source 
program and the subsequent formation of 
preprocessed text to be altered in either 
Of two ways: 

1. The executed statement may cause the 
preprocessor to continue the scan from 
a different point in the program. 
This new point may very well be one 
that has already been scanned. 
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The scan is terminated when an attempt 
is made to scan beyond the last character 
in the source program. The preprocessed 
text is completed and the second stage of 
compilation can then begin. 



Rescanning and Replacement 

For an identifier to be replaced by a 
new value, the identifier must first be 
a ctivate d for replacement. Initially, an 
identifier is activated by its appearance 
in a preprocessor DECLARE statement (i.e., 
a % DECLARE statement) . (It can be deacti- 
vated by appearing in a % DEACTIVATE state- 
ment and it can be reactivated by appearing 
in a % ACTIVATE statement.) After it has 
been activated initially, it must be given 
a replacement value. This is usually done 
via the execution of a preprocessor assign- 
ment statement. Once an identifier has 
been activated and been given a value, any 
occurrence of that identifier in text other 
than preprocessor statements is replaced by 
that value, provided that the identifier is 
still active when it is encountered by the 
scan. The new value is not immediately 
inserted into the preprocessed text, howev- 
er; it must be checked to see whether or 
not it, or any part of it, is subject to 
replacement by still another value (a 
rescan is made to determine this) . If it 
cannot be replaced, it is inserted into the 
preprocessed text; if it can be replaced, 
replacement activity continues until no 
further replacements can be made. Thus, 
insertion of a value into preprocessed text 
takes place only after all possible re- 
placements have been made. Note that the 
deactivation of an identifier causes it to 
lose its replacement capability but not its 
value. Hence, the subsequent reactivation 
of such an identifier need not be accom- 
panied by the assignment of a replacement 
value. 



For example, if the source program con- 
tained the following sequence of 
statements : 

% DECLARE A CHARACTER, B FIXED; 
%A = 'B+C* ; 
%B = 2; 
X = A; 



then the following would be inserted into 

the preprocessed text in place of the above 
sequence : 

X = 2 + C; 

In this example, the first statement is 
a preprocessor DECLARE statement that acti- 
vates A and E and also establishes them as 
preprocessor variables. (An identifier 
irust be established as a preprocessor vari- 
able before it can be assigned a value in a 
preprocessor statement; it can be so estab- 
lished only through a preprocessor DECLARE 
statement.) The second and third state- 
ments are preprocessor assignment state- 
ments; the second assigns the character 
string 'B+C' to A, and the third assigns 
the constant 2 to B- The fourth statement 
is a nonpreprocesscr statement 1 and, there- 
fore, is not executed at this stage. 
However, because this statement contains A, 
and A is a preprocessor variable that has 
been activated for replacement, the current 
value of A will replace it in that state- 
ment. Thus, the string *B+C' replaces A in 
the statement. But this string contains 
the preprocessor variable B, Upon checking 
E, the preprocessor finds that it has been 
activated and that it has been assigned a 
value of 2. Hence, the value 2 replaces B 
in the string. Further checking shows that 
2 cannot be replaced; scanning resumes with 
+C which, again „ cannot be replaced. Thus, 
the chain of replacements comes to an end 
and the resulting statement is inserted 
into the preprocessed text. 
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*For the purpose of this discussion, a non- 
preprocessor statement is any statement or 
set of one or more identifiers that appears 
in the source program but is not contained 

in a preprocessor statement, nor in a pre- 
processor procedure, nor in a comment. • 
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and one additional blank immediately after 
the C. 

Replacement values must not contain per- 
cent symbols, unmatched apostrophes, or 
unmatched comment delimiters. 

The following example illustrates how 
compile-time facilities can te used to 
speed up the execution of a DO- loop. 

A user might include the following loop 

in his program: 

DO 1=1 TO 10; 
Z<I)=X(I)+Y(I); 

END ; 

The following sequence would accomplish the 
same thing, but without the requirements of 
incrementing and testing during execution 
of the compiled program: 

%DECLARE I FIXED; 

%LAB:; 
Z(I)=X(I)+Y(I> ; 

%I=I+1; 

%IF I<=10 %THEN %GO TO LAB; 

% DEACTIVATE I; 
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The fourth statement, not being a pre- 
processor statement, is only scanned for 
replacement activity; it is not executed. 
The first time that this statement is 
scanned, I has the value 1 and has been 
activated. Therefore, each occurrence of I 
in this statement is replaced by 1 and the 
following is inserted into the preprocessed 
text being formed: 

Z( 1 )=X( 1 )+Y( 1 ) ; 

Note that each 1 is actually preceded by 
seven blanks of its own in addition to the 
one replacement blank shown. 

The fifth statement increments the value 
of I by 1 and the sixth statement, a pre- 
processor IF statement, tests the value of 
I. If I is not greater than 10 f the scan 
is resumed at the statement labeled LAB; 
otherwise, the scan continues with the text 
immediately following the %GO Ti, statement. 
Hence, for each increment of I, up to and 
including 10, the assignment statement is 



rescanned and each occurrence of 1 is 
replaced by its current value. As a 
result, the following statements are 
inserted into the preprocessed text: 

Z ( 1 )=XC 1 ) + Y( 1 ) ; 

Z( 2 )=~-X( 2 )+Y( 2 ); 



Z( 10 )=X( 10 )+Y( 10 ) ; 

As before, each number from 1 through 9 
is preceded by seven blanks in addition to 
the replacement blank shown; 10 is preceded 
by six blanks in addition to the replace- 
ment blank shown. 

When the value of I reaches 11, contrcl 
falls through to the %DEACTIVATE statement. 
This statement is interpreted as fellows; 
subsequent encounters of the identifier I 
in source program text are not to be 
replaced by the value 11 in the prepro- 
cessed text being formed; each I will be 
left unmodified, either for the remainder 
of the scan or at least until I is reacti- 
vated by a %ACTIVATE statement. If I is 
again activated, it will still have the 
value 11 (unless an intervening preproces- 
sor assignment statement has established a 
new value for I) . 



PREPROCESSOR VARIABLES 
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contextual or implicit declara- 
ntifiers is allowed in preprc- 
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The scope of a preprocessor variable 
encompasses all text except those prepro- 
cessor procedures that have redeclared that 
variable. The scope of a preprocessor 
variable that has teen declared in a pre- 
processor procedure is the entire procedure 
(there is no nesting of preprocessor 
procedures) . 

When a preprocessor variable has teen 
given a value, that value replaces all 
occurrences of the corresponding identifier 
in text other than preprocessor statements 
during the time that the variable is 
active. If the preprocessor variable is 



Section 15: Compile-Time Facilities 155 



inactive Cor if it has no value) , replace- 
ment activity cannot occur for the corre- 
sponding identifier. 



A preprocessor variabl 
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PREPROCESSOR EXPRESSIONS 
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Preprocessor expressions are written and 
evaluated in the same way as source program 
expressions, with tne following exceptions: 

1* The operands of a preprocessoi expres- 
sion can consist only of preprocessor 
variables, references to preprocessor 
procedures, decimal integer constants, 
bit- string constants, character-string 
constants, and references to tne 
built-in function SUBSTR. Repetition 
factors are not allowed with the 
string constants and the arguments of 
a reference to SUBSTR must be prepro- 
cessor expressions. 

2. The exponentiation symbol (**) cannot 

be used as an arithmetic operator. 
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The conversion of a fixed-point deci- 
mal number to a character string 
always results in a string of length 
8. (Leading zeros in the number are 
replaced by blanks and an additional 
three blanks are appended to the left 
end of the number, one of which is 
replaced by a minus sign if the number 
is negative . ) 



A character string in an expression 
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PREPROCESSOR PROCEDURES 
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A preprocessor procedure is an internal 
function procedure that can be executed 
only at the preprocessor stage. Its syntax 
differs from other function procedures in 
that its PROCEDURE and END statements must 
each have a leading percent symbol. The 
format of a preprocessor procedure is as 
follows : 



fllabel: 



PROCEDURE 



(label:]. . . 

( (identifier 

[, identifier] .«.)] 

{RETURNS (CHARACTER | FIXED) } ; 



(label: J . . .RETURN 

(preprocessor- expression) ; 



% (label:! 



END I label]; 
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INVOCATION OF PREPROCESSOR PROCEDURES 
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ruime used in that reference has been expli- 
citly declared with the ENTRY and RETURNS 
attributes in a ^DECLARE statement. This, 
ana not its appearance as a label of a 
^PROCEDURE statement, is what establishes 
it as an entry name; in fact, it is not 
even necessary for the preprocessor proce- 
dure to have been scanned before the 
reference is encountered (the procedure has 
only to be in the source program somewhere 
-- anywhere -- when the reference is 
encountered) . This is the only condition 
that must be met for a preprocessor proce- 
dure to be invoked by a reference in a pre- 
processor statement. 
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The value returned by a preprocessor 
function (i.e., the value of the preproces- 
sor expression in the RETURN statement) 
always replaces the function reference and 
its associated argument list. Note that 
for a reference made in a preprocessor 
statement, the replacement is only for that 
[articular execution of the statement; a 
subsequent scanning of the statement would 
again result in the invocation of the 
tunc tion. 



ARGUMENTS AND PARAMETERS FOR PREPROCESSOR 
FUNCTIONS 

The number of arguments in a preproces- 
sor function reference must always agree 
with the number of parameters accounted for 
in the ENTRY attribute specified for that 
function in a %DECLARE statement. If pa- 
rameters are not accounted for, the prepro- 
cessor assumes that the corresponding pro- 
cedure has none and no arguments are 
passed. If, however, parameters are 
accounted for, the preprocessor expects to 
find a parenthesized list of arguments, 
separated by commas and equal in number to 
the parameters accounted for in the proce- 
dure reference. The number of parameters 
accounted for in the ENTRY attribute and 
the actual number of parameters in the 
%PROCEDURE statement, however, need not be 
the same. The arguments are interpreted 



according to the type of statement ( prepro- 
cessor or nonpreprocessor) in which the 
function reference appears. The arguments 
in the argument list are evaluated before 
any match is made with the parameter list* 
If there are more arguments than parame- 
ters, the excess arguments on the right are 
ignored. (Note that for a function 
reference argument, the function is Invoked 
and executed, even if the argument is 
ignored later.) If there are fewer axgu- 
nents than parameters, the excess parame- 
ters on the right are given values of zero, 
for FIXEE parameters, or the null string, 
for CHARACTER parameters. The usual rules 
concerning the creation of dummy arguments 
apply if the function reference is in a 
preprocessor statement, but dummy arguments 
are always created if the function 
reference occurs in a nonpreprocessor 
statement. 

If the function reference appears in a 
nonpreprocessor statement, the arguments 
are interpreted as character strings and 
are delimited by the appearance of a comma 
or a right parenthesis occurring outside of 
balanced parentheses. For example, the 
argument list (A(B,C),D) has two arguments, 
namely, the string A(B,C) and the string D. 
Each argument is then scanned for possible 
replacement activity. Both the procedure 
name and its argument list must be found at 
one replacement level. Thus, only the com- 
mas and parentheses seen in the text being 
scanned when the procedure name is encoun- 
tered are considered in this context. 
After all replacements have been made, each 
resulting argument is converted to the type 
indicated by the corresponding parameter . 
attribute in the ENTRY attribute declara- 
tion for the function entry name (i.e., the 
ENTRY attribute declaration in the ^DECLARE 
statement) . No conversion is performed if 
a corresponding parameter attribute is not 
given in the ENTRY declaration. (The ENTRY 
attribute is discussed under "The %DECLARE 
Statement 1 " in Part II, Section 10, 
"Statements. w ) 

If the function reference appears in a 
preprocessor statement, the arguments are 
associated with the parameters in the nor- 
mal fashion. If there is a disagreement, 
the arguments aie converted to the attri- 
butes of the corresponding parameters as 
specified in the ENTRY attribute of the 
%DECLARE statement for the entry name. 
Only preprocessor variables, character- 
string constants, and fixed-point decimal 
constants can be passed to a preprocessor 
function invoked by a preprocessor 
statement. 

Returned Value 



The value returned by a preprocessor 
function to the point of invocation, is 
represented by the preprocessor expression 
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in the RETURN statement cf that function . 
Before being returned, this value is con- 
verted (if necessary) to the attribute 
(CHARACTER or FIXED) specified in tne 
RETURNS option oi tne fiirciicr.'u ^PROCEDURE 
statement. Tne attribute of the returned 
value must be consistent witn the attribute 
specified with the RETURNS attribute in the 
ENTRY attribute specification of the %DEC- 
LARE stateirent for the entry name. If the 
point of invocation is in a nonpreprocessor 
statement, the value is scanned for re- 
placement activity after it has replaced 
the function reference. Note that the re- 
placement of a function reference in a non- 
preprocesscr statement involves surrounding 
the replacement value by blanks (one blank 
on each end) in the sarr.e way that it does 
for the replacement of an identifier by the 
value of the preprocessor variable. 

Note that the rules fcr preprocessor 
expressions do not permit the value 
returned by a preprocessor procedure to 

contain preprocessor statements. 

Examples of Preprocessor Functions 

In the statements below, VALUE is a* 
preprocessor function procedure that 
returns a character string of the form 
argl (arg2) , where arg l and arg2 represent 
the arguments that have teen passed to the 
function • 

Assume that the source prograir contains 
the following sequence: 

%DECLARE A CHARACTER, 

VALUE ENTRY (CHARACTER, FIXED) 
RETURNS (CHARACTER) ; 
DECLARE (Z(10) f Q) FIXED; 
%A= ' Z s ; 
%VALUE: PROCEDURE (ARG1,ARG2) 

RETURNS (CHARACTER) ; 
DECLARE ARG1 CHARACTER, 

ARG2 FIXED? 
RETURN (ARG1 | | • ( ■ | | ARG2 | 
%END VALUE; 
Q = 6+VALUECA, 3) ; 



i) ») 



When the scan encounters the last state- 
ment, A is active and is thus eligible fcr 

replacement. Since VALUE is also active, 
the reference to it in the last statement 
causes the preprocessor to invoke tne pre- 
processor function procedure of that name. 
However, before the arguments A and 3 are 
passed to VALUE, A is replaced by its value 
Z (assigned to A in a previous assignment 
statement), and 3 is converted to fixel- 
point to conform to the attribute of its 
corresponding parameter. VALUE then per- 
forms a concatenation of these arguments 
and the parentheses and returns the conca- 
tenated value, that is, the string Z (3), 
to the point of invocation. The returned 
value replaces the function reference and 



the result is inserted into the prepro- 
cessed text. Thus, the preprocessed text 
generated by the above sequence is as fol- 
lows (replacement blanks are not shown) : 

DECLARE (Z(10) f Q) FIXED; 
Q = 6+Z(3) ; 

The preprocessor function procedure GEN 
defined in the following example can gener- 
ate GENERIC declarations for up to 99 pa- 
rameters. Only four are generated in this 
example, however. 

Assume that the source program contains 
the following sequence; 

%DCL GEN ENTRY (CHAR, FIXED, FIXED, 

CHAR) RETURNS (CHAR); 



DCL A GEN (A f 2 f 5, FIXED), . 



%GEN: PROC (NAME, LOW, HIGH, ATTR) 
CHAR; 
DCL (NAME, SUFFIX, ATTR, STRING) 
CHAR, (LOW, HIGH, I, J) FIXED; 
STRING=«GENERIC( ' ; 
DO I=LOW TO HIGH; /* ENTRY DCL 

LOOP */ 
IF I>9 

THEN SUFFIX=SUBSTR(I, 7 # 2) ; 

/* 2 DIGIT*/ 
ELSE SUFFIX=SUBSTR(I, 8, 1) ; 
/*1 DIGIT*/ 
STRING=STRING| | NAME | | SUFFIX | | 

• ENTRY ( ■ ; 
DO J=l TO I; /* PAR ATTR LIST*/ 
• STRING=STRING [ | ATTR; 
IF J<I /* PAR AM ATTR 

SEPARATOR */ 
THEN STRING=STRING | | s , f ; 
ELSE STRING=STRING | | ' > " ; 
END; 
IF KHIGH /* ENTRY DCL 

SEPARATOR*/ 
THEN STRING=STRING | | f , f ; 
ELSE STRING=STRING| j ' ) * ; 
END; 

RETURN (STRING) ; 
% END; 

The following is generated into prepro- 
cessed text : 

DCL A GENERIC (A2 ENTRY (FIXED, FIXED) , 

A3 ENTRY (FIXED, FIXED, 

FIXED) , 
A4 ENTRY (FIXED, FIXED, 

FIXED, FIXED) , 
A5 ENTRY (FIXED, FIXED, 

FIXED, FIXED, FIXED)), 

Ncte that the atove example refers to 
the built-in function SUBSTR, It is tne 
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only built-in function that can he invoked 
at the preprocessor stage. It can be 
invoked by a reference in either a prepro- 
cessor or a ncnpreprocessor statement. 

Use of the SUBSTR Built-in Function 



A reference to SUBSTR in 
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scr only if the name SUBSTR 
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tuilt-in function SUBSTR are 
the same way that arguments 
processor statement referenc 
cesser function are interpre 
as character strings. 
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A preprocessor statement reference to 
:UBSTR is always valid. 



IE PREPROCESSOR CO-GROUP 



The preprocessor DC-group can provide 
iterative execution of the preprocessor 
statements contained within the group. The 
format of the preprocessor EC-group is as 
follows: 



%[labe 



1:1... [DO i = mir"TC rr.2LBY m3]l;1 
L LEY iv3LTO rr.2]J J 



The oxpansica. >i. '. preprocessor DO-group 
is the same as tha t o!\own under the iion pre- 
processor CO statement in Part II r Section 

10, "Statements. " 

The exanplt- Lrlww i:«;suits in the sanit! 
expansion generated Lor the example of pre- 
processor lccp- expansion an the section 
"Rescanning and Replacement" in this 

chapter : 

% DECLARE I FIXED; 
%DO 1=1 TC 10; 
Z(I) = X(I)+y (I) ; 

%END; 
%DEACTIVATP 1 ; 

The second example under "Returned 
Value" shows how preprocessor DO-grcups can 
te used within a preprocessor procedure 
(percent symbols must be omitted, of 
course) . 



INCLUSION Or LX'i i ■ H NAL TEXT 

Strings of external text can be incorpo- 
rated into the source program at the pre- 
processor stage by use of the ^INCLUDE 
statement. Such text, once incorporated, 
is called i ncl uded text and may consist of 
both preprocessor and ncnpreprocessor 
statements. Hence, included text can con- 
tribute to the preprocessed text being 
f crrred. 

The general fern at and the rules govern- 
ing the use of the ^INCLUDE statement are 
presented in Part It, Section 10, 

"Statements. H 



%[latel:I... ENDllabel]; 

In the above format, i must be a prepro- 
cessor variable and ml, m2, and m3 must be 
preprocessor expressions. The label that 
can follow the keyword END must be one of 
the labels preceding the keyword CO. Pre- 
processor CO-groups may be nested and rnul- 
viple closure is allowed. 

Control cannot be transferred into a 
preprocessor EO-group specifying iteration, 
except by way of a return from a preproces- 
sor procedure invoked from within the 
group. 

Both preprocessor statements and text 
ether than preprocessor statements can 
appear within a preprocessor DC-group. 
However, only the preprocessor statements 
are executed; nonpreprocessor statements 
are scanned but only fcr possible replace- 
ment activity. 

Noniterative preprocessor DO -groups are 
useful as THEN or ELSE clauses of %IF 
statements. 



The text specitied by a ^INCLUDE state- 
ment is incorporated into the source pro- 
grair irrirediately after the point at which 
the statement is executed. The scan there- 
fore continues with the first character in 
the included text All preprocessor state- 
ments in this text are executed and re- 
placements are made where required. 

Preprocessor procedures whose declara- 
tions appear in externa], text can be 
invokeu only afie/ that external text 
teccnes included text. The result of a 
preprocessor procedure reference encoun- 
tered before that procedure has been incor- 
porated into the source program is 
undefined. 

Assuire that PAYRL is a member of the 
data set USERL1B and contains the following 

structure declaration: 

DECLARE 1 PAYPCIL, 
2 NAME, 

3 EAST CHARACTER (10) VARYING, 
3 FIRST CHARACTER (15) VARYING, 
3 MIDDLE CHARACTER (3) VARYING, 
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2 MANJMO FIXED DECIMAL C6 # 0) # 
3 REGLR FIXED DECIMAL C8 # 2), 
3 OVERTIM FIXED DECIMAL (8,2) # 

2 RATE, 

3 REG EAR FIXED DECIMAL (8,2), 
3 OVERTIME FIXED DECIMAL (8,2); 

Then the following sequence of prepro- 
cessor statements: 

^DECLARE PAYROLL CHARACTER; 

%PAYROLL^ f CUM_ PAY* ; 
XINCLUDE PAYRL; 
%DEACTIVATE PAYROLL; 
%INCLUDE PAYRL; 

will generate two identical structure 
declarations into the preprocessed text, 
the only difference being their names, CUM- 
__PAY and PAYROLL. Execution of the first 
%INCLUDE statement causes the text in PAYRL 
to be incorporated into the source program. 
When the scan encounters the identifier 
PAYROLL in this included ttxt, it replaces 
it by the current value of the active pre- 
processor variable PAYROLL , namely, CUM__- 
PAY. Further scanning of the included text 
results in no additional replacements. The 
scan then encounters the %DEACTIVATE state- 
ment. Execution of this statement deacti- 
vates the preprocessor variable PAYROLL and 
makes the identifier ineligible for re- 
placement. When the second %INCLUDE state- 
ment is executed, the text in PAYRL once 
again is incorporated into the source pro- 
gram. This time, however, scanning of the 
included text results in no replacements 
whatsoever, because none of the identifiers 
in the included text are active. Thus, two 
structure declarations, differing in name 
only, are inserted into preprocessed text. 



PREPROCESSOR STATEMENTS 



This section 
can be used at 
briefly discuss 
ments that have 
this chapter 
statements, the 
governing their 
section "Prepro 
II, Section 10, 



lists those statements that 
the preprocessor stage and 
es those preprocessor state- 
not yet been explained in 
All of the preprocessor 
ir formats, and the rules 
use are described in the 
cesser Statements" in Part 
Statements. " 



But first, some unrelated comments per- 
taining to preprocessor statements in gen- 
eral should be made: 

1. Some keywords appearing in preproces- 
sor statements can be abbreviated as 
shown in Part II, Section 3, "Keywords 

and Abbreviations. 1 * 

2. Comments can appear within preproces- 
sor statements wherever blanks can 
appear; however, such comments are 
never inserted into preprocessed text. 



All preprocessor statements can be 
labeled. Such labels must appear 
immediately following the % Ccnly 
blanks can intervene) . All labels 
must be unsubscripted statement label 
constants. (Labels on 56DECLARE state- 
ments ere ignored.) 



The functions performed by the following 
preprocessor statements have already been 
discussed in this chapter: 



% ACTIVATE 

% DEACTIVATE 

% DECLARE 

% DO 

% END 

% INCLUDE 

% PROCEDURE 
RETURN 

Note that the preprocessor RETURN state- 
ment cannot have a leading % because it can 
be used only within a preprocessor proce- 
dure, and all percent symbols must be 
omitted therein. 

Four other statements can be executed at 

the preprocessor stage: 

% assignment 
% GO TO 
% IF 
% null 

The preprocessor assignment statement is 
used to evaluate preprocessor expressions 
and to assign the result to a preprocessor 
variable. All of the examples shown in 
this section "make use of this statement. 

The % GO TO statement causes the prepro- 
cessor to interruption its sequential scan- 
ning and continue it elsewhere in the 
source program, specifically at the label 
specified in the % GO TO. Thus, it can be 
useful for rescanning or avoiding text. 



The % IF statement 
trol the sequence of th 
the value r£ a preproce 
must have a THEN clause 

ELSE clause. Each clau 
preprocessor statement 
must be preceded by a % 
statements is allowed a 
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an be used to con- 
e scan according to 
ssor expression. It 

and it can have an 
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The preprocessor null statement is the 
same as a nonpreprocessor null statement 
(except for the %) . It can be used to pro- 
vide transfer targets fur %GQ TO statements 
or it can be used in nested %IF statements 
to balance the %ELSE clauses. For example, 
*ELSE%; is a null ELSE clause. 
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SECTION 16; OPTIMIZATION AND EFFICIENT PERFORMANCE 



This section, concerned with general 
efficiency, provides information on the 
ways in which execution speed can be im- 
proved; and it includes a list of common 
errors to avoid. 



INTRODUCTION 

For a given application, several object 
programs are possible, each of which would 
produce the required result . However they 
would have varying degrees of efficiency in 
terms of machine time and storage use. The 
efficiency of a PL/I object program depends 
on two basic factors: 

1. The way in which the user writes the 
source program 

2- The way in which the compiler treats 
the source program 

These two factors are interrelated. The 
compiler can perform a limited amount of 
optimization (i.e., briefly, it can alter 
the program during compilation so that the 
object program uses less machine time but 
still gives the required result) ; but the 
user can control the degree of optimiza- 
tion, using the PL/1 options ORDER and 
REORDER and the OPT compiler option . 
Secondly, the compiler does not necessarily 
generate identical object code for a given 
PL/I item (such as an assignment) every 
time that item appears in a source program. 
For example, an assignment may be made 
either directly or via a compiler- created 
temporary variable; data conversion may be 
performed by in-line code or may require a 
library call. The method selected depends 
on the nature of the data. A knowledge of 
the circumstances in which the compiler 
generates more efficient object code can be 
borne in mind by the user while writing the 
source program. 

The remainder of this section deals with 
two main topics. The first, headedd 
•Effect of Compilation on Object Program 
Efficiency," deals primarily with the com- 
piler and the circumstances in waich it 
generates more efficient code. The second, 
headed "Programming Techniques," provides 
lists of hints that the user can follow to 
obtain different types of ef^xciency (e.g., 
reduced storage requirements; increased 
execution speed). It also provides a list 
of the errors most likely to be encountered 
when first using PL/I. 



EFFECT OF COMPI L ATION ON OBJECT PROGRAM 
EFFICIENCY 

The TSS/360 PL/I compiler is capable of 
optimizing loops and subscripts (see 
below) . This optimization requires the use 
of extra compiler phases, with a consequent 
increase in compilation time; moreover, the 
results are not guaranteed in certain cases 
of error. For this reason, provision is 
made for the user to control the degree of 
optimization by using the ORDER and REORDER 
options on the blocks within the PL/I pro- 
gram itself and by using the OPT compiler 
option in the PLI for a particular compila- 
tion of the program. 

The compiler will also, as part of its 
normal function (i.e., without, the use of 
special optimization phrases) , select the 
more efficient of two methods for many 
operations, provided that the nature of the 
data allows it to do so. Such operations 
include simple assignments, evaluation of 
string built-in functions, and data 
conversions. 



PL/I OPTIONS: ORDER AND REORDER 

Strictly speaking, the order in which 
the statements of a PL/ I source program are 
to be executed is specified by the order in 
which they appear in the source program, 
even if the code could be reordered so as 
to produce the same result more efficient- 
ly. The order of execution is normally 
sequential except where modified by a con- 
trol statement such as TO TO. (See "Con- 
trol Statements* in Part I, Section 5, 
■Statement Classification. *} 

The user can vary the degree of language 
stringency imposed on the compiler by using 
the ORDER and REORDER options on the PROCE- 
DURE and BEGIN statements. REORDER speci- 
fies a partial relaxation of the rules to 
allow the compiler more freedom in optimi- 
zation. This relaxation is such that if 
computational or system action interrupts 
occur during execution of the Mock, the 
result is not necessarily the same as it 
would be under the strict rules. 

The selected option applies to ail 
nested blocks unless overriden? if neither 
option is specified, the option that app- 
lies to the containing block will be 
assumed. If the block is an external pro- 
cedure, it will be assumed to have the 
ORDER option unless REORDER is explicitly 
specified. 
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The ORDER Option 

The ORDER option specifies that the 
normal language rules are not to be 
relaxed; i.e., any optimization must be 
such that the execution of a block always 
produces a result that is in accordance 
with the strict definition of PL/I, This 
means that the values of variables set by 
execution of all statements prior to compu- 
tational or system action interruption are 
guaranteed in an on-unit entered as a 
result of the interruptions or anywhere in 
the program afterwards* 



Note that the strict definition now 
allows the compiler to optimize common 
expressions ,* where safely possible, by 
evaluating them once only and saving the 

result r rather than reevaluating for each 

reference. 



The REORDER Option 

The REORDER option specifies that execu- 
tion of a block must produce a result that 
is in accordance with the strict definition 
of PL/ I unless a computational or system 
action interruption occurs during execution 
of the block; the result is then allowed to 
deviate as follows; 

1. After a computational or system system 
action interrupt has occurred during 
execution of the block, the values of 
variables modified, allocated, or 
freed in the block are guaranteed only 
after normal return from an on-unit or 
when accessed by the ONCHAR and 
ONSOURCE built-in functions, 

2. The values of variables modified* 
allocated, or freed in an on-unit for 
a computational or system action con- 
dition (or in a block activated by 
such an on-unit) are not guaranteed on 
return from the on-unxt into the 
block, except for values modified by 
the ONCHAR and ONSOURCE 

pseudo- variables . 

A program is in error if a computational 
or system action interruption occurs during 
the execution of the block and this inter- 
ruption is followed by a reference to a 
variable whose value is not guaranteed in 
such circumstances* 



*A common expression is an expression that 

occurs more than once in a program but is 
obviously intended to result in the same 

value each time that it is evaluated,, i.e., 

if a later expression is identical to an 
earlier expression, with no intervening 

modification to any operand, the expre- 
ssions are said to be common- 



Effect, of ORDER and RE ORDER Options — 
Example 

The following example illustrates the 
effect of the ORDER and REORDER OPTIONS: 

X: PROCEDURE ORDER; 

DECLARE CA f B,C> (10,10); 

ON OFL PUT LIST (•UFL WHEN M= f , M) ; 

ON OFL BEGIN | 

PUT LIST ( s OFL WHEN M=°,M>? 

GO TO RESTART; 

END; 

RESTART: GET DATA CM, B,C,D, K) I 
CALL Y; 

PUT DATA CM, A) ; 
GO TO RESTART; 

Ys PROCEDURE REORDER; 
DO I = 1 TO 10} 
DO J = 1 TO 10; 

A(I,J)=B€I*K,J)+C(J,I*K)*C(K+1,1) 
♦D/I+D/K; 
END; END; 
END Y; 

END X; 

In this example, since the values of D and 
K are not modified anywhere in procedure Y, 
the compiler is permitted to keep 1 and J 
in registers and move the computation of 
the expression I+K outside of the inner 
loop; in addition, since the expression K*l 
does not depend on 1 or J f it can be eva- 
luated outside of both loops* If this 
movement is carried out, the expression I+K 
will be evaluated ten times instead of 100 
times, and the expression K+l will be eva- 
luated once instead of 100 times. Any 
attempt to use A, l f or J after an overflow 
interruption in procedure Y, and before 
another value has been assigned to them, 
would be an error. 

Computation of the expressions D/I and 
D/K cannot be moved, because they are not 
subscript expressions. 



COMPILER OPTION: OPT=N 

The OPT compiler option, specified in 
the PL/I command for a compilation, allows 
the user to control the optimization for a 
particular compilation* The option can be 
specified with one of three values: 

OPT^O requests fast compilation and, as a 
secondary consideration, reduction 
of the storage space required by 
the object program at the expense 
■of execution time* 

OPT=l requests fast compilation and, as a 
secondary consideration, reduction 

of object, program execution time at 
the expense of storage space- 
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OPT=2 requests reduction of object pro- 
gram execution time at the expense 
of compilation time. 

The extra optimization phases of the com- 
piler (i.e., those concerned mainly with 
loop and subscript optimization) are 
invoked only when OPT=2 is specified. 



LOOP AND SUBSCRIPT OPTIMIZATION 

Four types of loop 1 - and subscript opti- 
mization are attempted by the? compiler when 
the compiler option OPT=2 is specified. 
However, the compiler will not necessarily 
be able to perform the optimization in 
every case; its ability to do so is 
affected by several factors, such as the 
use of subscripts nested within subscripts, 
the use of loops containing procedure or 
begin blocks, or the choice of ORDER and 
REORDER options. 

The section headed "Methods ol Improve- 
ment When OPT=2," under "Improving Speed of 
Execution," later in this chapter, gives a 
list of rules that the user should follow, 
when using OPT=2, so as to give the compil- 
er the best chance of carrying out the loop 
and subscript optimization. In the 
descriptions of the four types of optimiza- 
tion, below, the indicated choice of block 
option should be interpreted as follows; 
where it is indicated that optimization 
will be effected for both ORDER and REORD- 
ER, the specification of REORDER will pro- 
bably result in the greater degree of opti- 
mization; however, even where* REORDER is 
stated to be necessary for a particular 
type of optimization, there will usually be 
some optimization when ORDER is specified. 

The four types of loop and subscript 
optimization are as follows: 

1. Loop control mechanism: The object 
code for loop control (i.e., the 
necessary comparison and branching 
instructions generated by the compil- 
er) will be simplified wherever poss- 
ible. The block option may be ORDER 
or REORDER. 

2. Loop control variables: The object 
code for control variables used as 
subscripts will be simplified wherever 
possible. The block option should be 
REORDER. 



1 For the purpose of this discussion, a loop 
is considered to be either an iterative 
DO-group or an array expression. The dis- 
cussion does not apply to loops specified 
by GO TO statements or to repetitive speci- 
fications in data lists for stream-oriented 
transmission. 



3. Array expressions: Array expressions 
Cwhich are effectively a type of loop, 
since the specified operation is per- 
formed on each element in turn) will 
be optimized by a combination of the 
two techniques mentioned above. The 
block option may be ORDER or REORDER. 

<*. Subscript lists: Common expressions 
appearing in subscript lists are eval- 
uated at the point of the first occur- 
rence of the common expressions, and 
the result is saved for other occur- 
rences of the expression. (This app- 
lies both inside and outside of 
loops.) Subscript expressions that 
occur within a loop, but whose values 
never change during the execution of 
the loop, are evaluated outside of the 
loop. The block option should be 
REORDER. CNote the difference between 
the two types of expression and their 
treatment: a common expression, which 
appears more than once in the program, 
is evaluated at its first occurrence; 
the other type of expression, which 
occurr within a loop and has a value 
that remains constant throughout all 
the iterations of the loop, is evalua- 
ted before it occurs. In the latter 
case, therefore, the compiler reorders 
the code. ) 



ASSIGNMENT HANDLING 

When the expression on the right-hand 
side of an assignment statement is an 
operational expression, or where data con- 
version is necessary, the assignment is 
usually made via an intermediate temporary 
which holds the result of the expression. 
(See Part I, section 4, "Expressions and 
Data Conversion.") However, the TSS/360 
PL/I compiler produces optimized code that 
does not use temporary storage in the fol- 
lowing cases, provided that the FIXEDOVER- 
FLOW and SIZE conditions are disabled or 
cannot be raised, and provided that the 
operands are of suitable scale and 
precision: 

1. Simple fixed decimal assignments (for 
example, A = A + constant; X = A ♦ B ; ■ 
X = A * B ♦ C ; ) . 

2. Simple expressions and assignments 
that involve only character- string 
variables and character-string con- 
stants (for example, A = A||B;). 

3. Assignments between temporary 
variables such as occur in some func- 
tion references. 

The block option may be ORDER or REORDER, 
and the OPT compiler option may have any of 
the three possible values. 
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INLINE OPERATIONS 

Operations are performed at execution 
time in two different ways* they may he 

handled by calls to PL/I library routines 
or they may be handled directly by inline 
code. The saving in execution time fox an 
operation performed inline can be of the 
order of ten to one or more in relation to 
a similar operation handled by a library 
call; the overall effect on program execu- 
tion will depend on the number of times ' 
these operations are used in a program* It 
will repay the user, therefore, to recog- 
nize those operations that are performed 
inline and those that require a library 
call f and to arrange his program to use the 
former wherever possible. The majority of 
the inline operations are concerned with 
data conversion and string handling • 

Data Conversion 

The data conversions performed inline 
are shown in Figure 20. A conversion out- 
side the range or condition given, or 
marked "Not done," is performed by a 
library call. 



Not ail of the picture characters avail- 
able can be used in a picture specification 
involved in an arithmetic conversion. The 

only ones permitted are: 



1. V and 9 



2- Drifting or nondrifting characters $, 



3. Zero suppression characters Z, * 

4. Insertion characters , , . # /, B 

For inline conversions, picture specifica- 
tions with this subset of characters are 
divided into three types: 



Picture type 1 : Picture specifications 
consisting entirely of 9s with (optionally) 
a V and a leading or trailing sign or cur- 
rency symbol and up to four insertion 
characters. Examples of type 1 pictures are 
•99V999', f 99', , S99V9«, , 99V+ i , '$99.99" 



T . . . _ 1 

Minimum Opti- 
mization Code 



H- 



r- 



Conversion 
. - T „. — ._ - 



Source 



FIXED BINARY 



H- 



Target 

FIXED BINARY 
FIXED DECIMAL 

FLOAT 

Bit string 



Character string 

or Picture 



Comments and Condition 



If either scale factor = and the 

other scale factor < 0, then the opt. 
code may be 

If source scale factor = 0, then the 
opt. code m^y be (whether SIZE is 
enabled or not) 

String must be fixed-length, ALIGNED, 
and with length <256 

Source scale factof must be > 

String must be fixed-length with 
length <256 Picture types 1, 2, or 3 
(See "Picture Conversions Not 
Performed Inline.") 



SIZE 
Disabled 



SIZE 
Enabled 





1 



Not done 



Not done 



FIXED DECIMAL 



FIXED BINARY 

FIXED DECIMAL 

FLOAT 

Bit String 



If source and target scales have the 
same sign and are nonzero, then the 
opt. code (SIZE disabled) must be 1 



Source precision must be <10 

Source scale factor must be zero 
String must be fixed- length, ALIGNED, 
and with length <256 






1 o 


1 


! i 





| Not done 



Figure 20. Implicit Data Conversions Performed Inline (Part 1 of 2) 
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h~~ 



I— 



Conversion 



1 



Source 



FIXED DECIMAL 



FLOAT 



Bit string 



Target 



Character string 



Picture 



FIXED BINARY 
FIXED DECIMAL 
FLOAT 

Bit string 



._+. 



FIXED BINARY 



FIXED DECIMAL 
and FLOAT 

Bit string 



-+- 



\~ 



Comments and Condition 



Source scale factor must be > 
String must be fixed- length and 
length <256 

Picture types l f 2 f and 3. For 
picture types 1 and 2 with no sign, 
the Opt. code may be 0. (See 
"Picture Conversions Not Performed 
Inline.*) 



Target precision must be <9 

Source and target may be single or 
double length 

String must be fixed-length, ALIGNED, 
and with length <256 



Source string must be fixed-length, 
ALIGNED, and with length <256 

Source must be fixed-length, ALIGNED, 
and with length<32 

Source and target must be ALIGNED 
with length <2040 



Minimum Opti- 
mization Code 



SIZE 
Disabled 



1 
1 





Not done 
Not done 



Not done 



--+ ^ 

[Not done 



Not done 



SIZF 
Enabled 



Not done 



H 



Character 

string: 

Fixed-length 



VARYING 



Character strings 
Fixed- length 
VARYING 



Character string 
(VARYING) 



Target length must be ^256 
Source and target lengths must be 
<256 

Source and target lengths must be 
<256 



-+ 



Picture 



Character string 



Picture 



String must be fixed-length with 
length <256 

Pictures must be identical 



+ --■ 







Picture 
type 1 



J- 

Label 

Figure 20 



FIXED BINARY 
FIXED DECIMAL 

FLOAT 

Picture 

Label 

Pointer /Off set 



Source precision must be <10 

If picture has a sign, then the opt* 
code must be 1 



Source precision must be 10 

Picture types 1, 2, or 3 

4 . _ . . „. 



Pointer/Offset 



1 


1 
1 





Not done 

Not done 

Not done 

Not done 

+- — 










Implicit Data Conversions Performed Inline (Part 2 of 2) 
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Picture type 2 : Picture specifications 
with zero suppression characters and 
(optionally) insertion characters and a 
sign of currency symbol character. Also, 
type 1 pictures with more than four inser- 
tion characters* Examples of type 2 pic- 
tures are i ZZZ s # •♦*/*9«, •ZZ9V.99 , f «*ZZ. 
ZZ f , f $/////99 s . 

Picture type 3 : Picture specifications 
with drifting strings and Coptionally) ins- 
ertion characters and a sign or currency 
symbol character. Examples of type 3 pic- 
tures are s $$$$ s , •-,-- 9 f f , S/SS/S9 i , 
**+*9.V9\ s $$$9- f 

| PICTURE CONVERSIONS NOT PER F ORMED INLINE ; 
Sometimes a conversion involving a pictured 

item is not performed inline even though 
the picture specification conforms to one 

of the above types* This may be because : 

1. The optimization code value COPT=n) is 
too low* 

2. SIZE is enabled* 

3. There is no overlay between the 'digit 
positions in the source andthe target. 
{For example: a conversion from FIXED 
DECIMAL (6,8) or FIXED DECIMAL C5,~3> 

to PIC t 99V99 i will require a library 

call.) 

*»• The picture specification may have 

certain characteristics that make the 
conversion difficult to handle inline : 

a* An insertion character between a 
drifting Z or a drifting * and the 
first 9 is not preceded by a V 
Cfor example, •ZZ.99M. 

b. There are drifting or zero 

suppression characters to the 
right of the decimal point Cfor 
example, •ZZV.ZZS •♦♦V** t ). 

String Handling 

The string operations and built-in func- 
tions performed inline are shown in Figures 
21 and 22. Note that even the string func- 
tions indicated as always being performed 
inline may sometimes require a library 
call. For example* if the expression in 
the BIT or CHAR function requires an impli- 
cit conversion not handled inline, the 
appropriate library routine will be called. 



scripts (see "Effect of Compilation on 
Object Program Efficiency," above). Howev- 
er, there is a significant increase in com- 
pilation time and results are not guaran- 
teed in certain cases of error . The recom- 
mended procedure is to specify REORDER 
where possible in the program but to sup- 
press the optimization phases in the early 
stages of developing the program, by using 
OPT=0 or lj when the program is fully deve- 
loped it can be compiled during OPT=2. 

Even when OPT-0 or 1 is specified, the 

user can increase the execution speed by 
following certain rules? and when OPT=2 is 
specified, he can increase the amount of 
optimization by following another set of 
rules. For this reason, the information in 
this part is given first in terms of OPT=0 
or 1, and then in terms of OPT~2. 



Methods of Improvement W h en OPT-0 or 1 

The following measures are suggested for 
use where both compilation time and execu- 
tion time are important factors. Note that 
while some of these measures may slow down 
the compilation, this is offset by the fact 
that others will accelerate it. In the 
main, there should be no serious increase 
in compilation time. 

1. If the use of storage is not as impor- 
tant as speed of execution, use OPT=l. 
Avoid the STMT option. 

2. Avoid unnecessary program segmentation 
and block structure; all procedures, 
ON-units and BEGIN blocks need pro- 
logues and epilogues, the initializa- 
tion and housekeeping for which carry 
a considerable overhead. (Prologues 
and epilogues are described in Appen- 
dix C of this publication.) Whenever 
possible, use GOTO of IF statements to 
control program logic, rather than the 
CALL statement. 

3. Branching in IF statements can be im- 
proved by using DO and END statements 
to bracket a THEN clause, rather than 
using a GOTO statement in the THEN 
clause* For examples 

IF A=B THEN DO; 
C=D? 
E=F; 

END? 



PROGRAMM I NG T ECHNIQUES 

IMPROVING SPEED OF EXECUTION 

By using the OPT=2 compiler option and 
the REORDER block option, the user allows 
the compiler to optimize loops and sub- 



L : etc « 
is more efficient than 

IF A ^B THEN GO TO L; 

C=D; 

E^F; 
Lf etc. 
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When GO TO is used in an IF statement, 
more efficient object code is produced 
by the GO TO if it refers to a label 
within the same block rather than to a 
label outside the block. 
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r T 

(String Operation 



Comments and Conditions 



Source 



h 



Target 



Assign 



<OPT=0) 



Note: The assign- 
ment VARYING string 
to fixed-length 
string is not 
handled inline 



Nonadjustable, ALIGNED, fixed- 
length tit string <20*48 bits 
long 

Nonad justable, ALIGNED, bit 
string <20U8 bits long 

Nonadjustable, UNALIGNED, fixed- 
length bit string that is a 
scalar element of an AUTOMATIC, 
BASED or STATJC structure with 
no adjustable bounds or extents 



Fixed-length or VARYING 
character string <256 characters 
long 



Nonadjustable, ALIGNED, fixed- 
length bit string <2048 bits leng 



Nonadjustatle, ALIGNED VARYING 
bit string <2048 bits long 

Nonad justable, UNALIGNED, fixed- 
length bit string that is a 
scalar element of an AUTOMATIC, 
EASED or STATIC structure with no 
adjustable bounds or extents. The 
string must be 1 bit long. 

Fixed-length or VARYING character 
string <256 characters long 



h 



• And f , 'Not' , 'Or' 

Compare 

Concatenate 
STRING function 



h 



Nonadjustable, ALIGNED, fixed-length or VARYING bit strings, with 
lengths 

fixed-length - <2048 bits 

VARYING - <32 bits 

Nonadjustable fixed-length character strings <256 characters long 
Nonadjustable, ALIGNED, fixed-length or VARYING bit strings, with 
length: 

fixed-length - <2048 bits 

VARYING - <32 bits 
Nonadjustable fixed-length or VARYING character strings <256 
characters long 
Scalars and nonadjustable contiguous array or structure variables 



Notes: 



1. Operations with VARYING strings require 0FT=1. 

2. If the expression in IF statement is a bit string satisfying the conditions fcr 
the source string when OPT=0, then, if the string is <10 tits long, inline code 
is generated to test the value of the string. 

L .-. . . . . . 

Figure 21, Conditions Under Which the String Operations are Handled Inline 



5. Keep IF clauses simple; separate any 
multiple conditions into a series of 
simple IF statements. For example: 

IF A=B 

THEN IF C=D 
THEN IF E=F 

THEN GO TO M; 

6. Avoid extensive use of adjustable 
arrays and/or CONTRCILED storage. 

7. Use constants wherever possible 
instead of expressions. 

8. Exercise care in specifying precision. 
For example: 

DCL A FIXED DEC(8,4D r 
B FIXED DEC(10,2), 



C FIXED DEC CIO, 1 ) ; 



9. 



C=A+B; 



This requires almost twice as much 
code as it would if B had been 
declared (10,4), because the evalua- 
tion of A+B requires a scale factor of 

a. 



Use the PICTURE attribute only when 
necessary. For example, use FIXED 
DECIMALS, 2) instead of PIC i 999V99'. 
If a picture field is used in mere 
than one arithmetic operation, convert 
it once and then use the new form in 
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r --t 

String 
Function 



Comments and Conditions 



BIT [Always 

BOOL [Nonadjustable, ALIGNED bit str- 
ings, where the third argument 
is one of the logical operators 
'and', •not', 'or' or exclusive 
•or' 

CHAR (Always 

INDEX | Second argument must be a non- 
adjustable character string 
<256 characters long 

LENGTH | Always 

SUBSTR fSTRINGRANGE must be disabled 

TRANSLATE | First argument must be a fixed- 
length character string of 
length <256. If a third argu- 
ment is given, both second and 
third arguments must be 
character-string constants; if 
a third argument is not given, 
the second argument may be any 
fixed-length character-string 
argument, including constants. 

UNSPEC [Always 

VERIFY (Both arguments must be fixed- 
length character strings of 
length <256. If second argu- 
ment is a constant, the func- 
tion is partially performed at 
compile time. If both argu- 
ments are variables, the func- 
tion is performed at execution 
time* In both cases, no 
library call is necessary. 

i_„__. X- .__ . . . 1 

Figure 22. Conditions Under Which the 

String Functions are Handled 
Inline 

each operation. This holds for any 
conversion required more than once. 

If it is necessary to use data with 
the PICTURE attribute in arithmetic 
expressions, use pictures that will be 
handled in-line, as this considerably 
reduces execution time. Pictures with 
all 9s, a V and a nondrifting sign are 
particularly useful. For example: 

•999* 
'$99v99 f 
«$99' 
•V999 1 

10. Internal switches and counters, and 

data involved in substantial computa- 



tion or used for subscripts, should be 
declared BINARY; data required for 
output should be kept in DECIMAL forir. 

11. Keep data conversions to a minimum. 

Some possible methods follow: 

a. Use additional variables. For 
example, if a problem specifies 
that a character variable has to 
be regularly incremented by 1, 

DCL CTLNO CHAR (18); 



CTLNO = CTLNO* 1; 

requires two conversions, while 

ECL CTLNO CHAR (8), 
DCTLNO DEC FIXED; 



DCTLNO=DCTLNO+l ; 
CTLNO= DCTLNO; 

requires only one conversion. 

b. Take special care to make struc- 
tures match when it is intended to 
move data from one structure to 
another. 

c. Avoid mixed mode arithmetic, espe- 
cially the use of character str- 
ings in arithmetic calculations* 

12. Declare arrays in the procedure in 
which they are used, instead of pas- 
sing them as arguments. Declare sub- 
script variables in the block in which 
they are used, as FIXED BINARY. 

13. In multiple assignments to subscripted 
variables, restrict the assignment to 

three variables. 

14. If a subscripted item is referred to 
more than once with the same sub- 
script, assign the element to a scalar 
variable: 

K= CA CI > +1/A CD ) +A C i) **A (I) ; 

should be replaced by 

ASUB=ACI); 

R= C ASUB+1/ASUB) +ASUB**ASUB; 

15. Bit strings should, if possible, be 
specified as multiples of eight bits. 
Bit strings used as logical switches 
should be specified according to the 
number of switches required. In the 
examples below, Ca) is preferable tc 
(b), and Cfc) to (c): 
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1. Single Switches 

(a) DCL SW BITC1) INIT ( § 1 § B); 



IF 



(b) DCL 



IF 



(c) DCL 



IF 



SW THEN DO; 



SW BIT(8) INIT 'l'B); 



SW THEN DO; 



SW BITC8) INIT C'l'B); 



SW = • 10000000 f B THEN DO; 



2. Multiple Switches 
(a) DCL B BITC8); 



B = , 11100000 , L; 



IF 



<b) DCL 



B = i lll , B; 



IF 



(c) DCL 



IF 



B = •lllOOOOO'E THEN DO; 



B BIT (3); 



B = ' lll f B THEN DO; 



(SW1,SW2,SW3> BIT(l); 



SW1, SW2, SW3, = U'B; 



SWlfcSW2iSW3 THEN DO; 



If bit string data is to be held in 
structures, such structures should be 
declared ALIGNED. 



16. Avoid where possible use of unaligned 
bit-strings as they usually cause 
library subroutines to be invoked. 

17 • Concatenation operations are 

t ime~ consuming . 

18. Varying- length strings are not as 
efficient as fixed-length strings. 

19. Fixed-length strings are not efficient 
if their length is not known at com- 
pile time, as in this example: 

DCL A CfiAR(N); 

20. Avoid using the SIZE, SUBSCRIPT RANGE, 
STRINGRANGE and CHECK ON-conditions, 
except during debugging. Debugging 
aids should be removed from the pro- 
gram before running it ^s a production 
job. 

21. Do not refer to the DATE built-in 
function more than once in a run; it 
is expensive. Instead, refer to the 
function once and save the value in a 
variable for subseguent use; e.g., 
instead of 

PAGEA=TITLEA [ | DATE; 
PAGEB=TITLEB| | DATE; 

it is more efficient to Write 

DTE=DATE; 

PAGEA=TITLEA( |DTE; 
PAGEB=TITLEB| | DTE; 

22* Allocate sufficient buffers to prevent 
the program becoming I/O bound. 

23. Use blocked output records. 

2<*. Open a number of files in a single 
OPEN statement. 

% 25. In STREAM I/O, use long data lists 
instead of splitting up I/O 
statements „ 

26. Use EDIT-directed I/O in preference to 
LIST- or DATA- directed. 

27. Consider the use of overlay defining 
to simplify transmission to or from a 
character string structure. Example: 

DCL 1 IN, 

2 TYPE CHARC2) , 
2 REC, 

3 A CHARC5), 
3 B CHAR (7) , 
3 C CHAR C 66) ; 
GET EDITC1N) 
(AC2),A(5),A(7J7) ,A(66)> ; 

In the above example, each format- 
item/data-field pair is matched separ- 
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ately* code being generated for each 

matching operation. It would be more 
efficient to define a character string 

on the structure and apply the GET 

statement, to the string; 

DCL STRNG CHAR C 80) DEF IN; 



GET EDIT CSTRNG) CA(80)>; 



tational or system action condi- 
tions if the compilation contains 
on-units for such conditions. 
(For example, if the compilation 
contains an on- unit for an I/O 
condition, the use of I/O state- 
ments within loops should be 
avoided wherever possible* ) 

8. Arrays that are parameters and/or do 
not have constant bounds* 



Methods of Improvement When OPT=2 

When it is intended that OPT=2 will be 
used for the final compilation, the user, 
should use REORDER wherever possible and 
should observe the following points while 
writing the program. (Note that this 
information is *given for guidance onlys 
full optimization may not necessarily take 
place if the advice is followed,- converse- 
ly some optimization may take place if t^ie 
adv? ;e is not followed, ) The following 
items obstruct loop and subscript optimiza- 
tion , and should be avoided wherever 
possible: 

1. Subscript expressions that are not 
fixed-point binary or that contain 

nested subscripts or function 
references. 

2. The SUBSCRIPTRANGE condition; this , 

should be enabled only when necessary, 

3. DO statements that have more than one 

iterative specification and/or a WHILE 

clause. 

4. Control variables that are not real. 
fixed-point binary integer element 
variables. 

5. Expressions in TO and BY clauses other 
than decimal integer constants or 
single variables and expressions of 
real fixed-point binary integer type. 

6. The SIZE condition when enabled for 

iterative DO statements. 

7. Loops that contain any of the 
following: 

a. GET DATA statements 

b. References to user-defined 
functions 

c. Procedure calls 

d. Procedures or begin blocks 

e. Statements that are likely to 
raise conditions other than compu- 



9. Any of the followinq types of 
variable: 

a. Variables with the EXTERNAL 
attribute. 

b. Based variables and variables that 
are either defined or defined 
upon. 

c. Variables that are parameters. 

d. Variables used as arguments to 
either the ADDR built-in function 
or a user-defined function return- 
ing a pointer value* 

e. Variables used as arguments to an 
internal procedure when there are 
any pointers in the compilation. 

f. Variables used as arguments to 
external procedures (other than 
built-in functions) when there are 
any external pointers in the com- 
pilation or when any argument to 
one such procedure is an internal 
pointer. 



AVOIDING COMMON ERRORS 



This is a lis 
falls most likel 
writing a PL/I s 

Items concern mi 
language rule 
failure to obser 
ventions and res 

PL/I compiler, a 

appearing after 



t of the errors and pit- 

y to be encountered when 
ource program. Some of the 
sunderstood or overlooked 
while others result from 
ve the implementation con- 
trictions of the TSS/360 
nd are indicated by (I) 
the item. 



Source Program and General Syntax 

1. Ensure that the source program is com- 
pletely contained within the margins 
specified by the SORMGIN 

option. CI) 

2. Inadvertent omission of certain sym- 
bols may give rise to errors that are 
difficult to trace. Common errors 

are: unbalanced apostrophes; 
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5. 



unmatched parentheses; unmatched com- 
ment delimiters (e.g., /* punched 
instead of */ when closing a comment) j 
and missing semicolons. 

Reserved keyword operators in the 48- 
character set (e.g., GT f CAT) must in 
all cases be preceded and followed by 
a blank or comment. 

Care should be taken to ensure that 
END statements correctly match the 
appropriate DO, BEGIN, and PROCEDURE 
statements. 

In some situations, parentheses are 
required when their necessity is not 
immediately obvious. In particular, 
the expression following WHILE and 
RETURN must be enclosed in 
parentheses . 



In a PICTURE decla 
character indicate 
but does not in it 
decimal point on o 
picture character 
output, but is pur 
character and does 
scale factor. In 
however, the point 
scale factor. For 



ration, the V 

s the scale factor, 

elf produce a 
utput. The point 
produces a point on 
ely an editing 

not indicate the 
a decimal constant, 

does indicate the 

example: 



DCL A PIC , 99.9 I , 

E PIC 1 99V9 1 , 

C PIC99.V9' ? 
A, B,C=45.6; 
PUT LIST CA,B,C) ; 

This will cause the following values 
to be put out for A, B, and C, 
respectively: 



Program Control 

1. The procedure to be given initial con- 
trol at execution time must have the 
OPTIONS (MAIN) attribute. If more than 
one procedure has the MAIN option, the 
first one gets control. (I) 

2. When a procedure of a program is 
invoked while it is still active, it 
is said to be used recursively . 
Attempting the recursive use of a pro- 
cedure that has not teen given the 
RECURSIVE attribute may result in a 
program interruption after exit from 
the procedure. This will occur if 
reference is made to AUTOMATIC data of 
an earlier invocation of the 
procedure. 

Declarations and Attributes 

1. DECLARE statements for AUTOMATIC 

variables are in effect executed at 
entry to a block; sequence of the fol- 
lowing type are therefore likely to 
lead to unpredictable storage 
requests: 

A : PROC ; 
N=4; 
DCL B(N) FIXED; 



04.5 



456 



45.6 



If these values were now read back 
into the variables by a GET LIST sta- 
tement, A, B, and C would be set tc 
the following respective values: 



004 



56.0 



45.6 



If the PUT statement were then 
repeated, the result would be: 



00.4 560 45.6 

rnal declarations of the 

er must not specify con- 

ibutes, either explicitly 

If this occurs the 

not be able to detect 
PL/I also requires that 

value is specified in 
on of a STATIC EXTERNAL 

same INITIAL value 

in every declaration of 



Separate exte 
same identifi 
flicting attr 
of by default 
compiler will 
the conflict, 
if an INITIAL 
one declarati 
variable, the 
should appear 
that variable 



An identifier cannot be used for more 
than one purpose within its scope. 
Thus, the use of X in the following 
sequence of statements would be in 
error: 

PUT FILE (X) LIST (A,B,C); X=Y+Z; 
X : M=N i 



END; 

Missing commas in DECLARE statements 
are a common source of error. For 
example, a comma must follow the entry 
for each element in a structure 
declaration. 

External identifiers should neither 
contain more than seven characters, 
nor start with the letters IHE. (I) 



7. It is advisable to declare all entry 
points, associated parameter lists, 
and any return values, to avoid inad- 
vertent clashes of attributes. 

If the attributes of the data items in 
an argument list do not match those 
declared for the ENTRY, a dummy argu- 
ment is created with the correct 
attributes, and the data item is con- 
verted into the dummy. For example: 
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DCL X ENTRY (FIXED, CHAR (4)), 
Y FIXED, Z FIXEDC1, 0) ; 

¥=45; 

Z=0; 

CALL X(Y, Z) ; 

X:PROC(A f B) ; 
DCL A FIXED, 

B CHAR C 4) ; 

END? 

In the above example, a dummy is 
created for the second argument, Z, 
and is passed to X as 'bbbO'. 

If the attributes declared for X in 
the entry name declaration were incom- 
patible with the attributes of the 
arguments in the CALL statement, the 
compiler would issue a diagnostic mes- 
sage, and at execution time no conver- 
sion would take place. However, if 
the attributes declared for X in the 
entry name declaration conflicted with 
the attributes of the corresponding 
parameters in the PROCEDURE statement, 
the compiler would not detect the dis- 
agreement, and at execution time the 
consequences of such an error would, 
in general, be unpredictable. For 
example, if X were declared 

DCL X ENTRY (FLOAT, CHARU); 



8. When a data item .requires conversion 
to a dummy, and the called procedure 
alters the value of the parameter, 
note that the dummy is altered, not 
the original argument. For example: 



DCL X ENTRY (FIXED, FIXED), 

A FIXED, 

B FLOAT; 
CALL XCA, B) ; 



X:PRCC(Y, Z) 

DCL (Y r Z) 
Y=Z**100; 

Z=Y**3? 

END X; 



FIXED; 

/*A IS ALTERED IN 

CALLING PROC*/ 
/*B IS UNALTERED IN 

CALLING PROC*/ 



When the attributes for a given iden- 
tifier are incompletely declared, the 
rest of the required attributes are 
supplied by default. The following 
default assumptions should be careful- 
ly noted. 

FLOAT DECIMAL REAL is assumed for 
implicitly declared arithmetic 
variables, unless the initial letter 
is in the range I through N, when 
FIXED BINARY REAL is assumed. 



then 45 would be passed as FLOAT, but 
would be interpreted by X as FIXED, 
possibly with disastrous results. 

Similarly, attributes declared for 
RETURN values must agree in the invok- 
ing and invoked procedures; however, 
the actual expression returned may be 
of any data type and will be converted 
to that declared. For example: 

DCL X RETURNS (CHARU)); 

DCL A CHAR (4) ; 

X: PROC CHAR (4) ; 
RETURN (I*J*K); 
END X; 



If a variable is explicitly declared 
and any of the base, scale, or irode 
attributes is specified, the others 
are assumed to be ffoir. the set FLOAT/ 
DECIMAL/REAL. For example: 



DCL I; 



DCL J REAL; 



/*! IS FIXED BINARY 

(15,0) REAL 
AUTOMATIC*/ 

/*J IS FLOAT DECIMAL 
(6) REAL 
AUTOMATIC*/ 



DCL K STATIC; /*K IS FIXED BINARY 
(15,0) REAL 
STATIC*/ 



A=X; 

The precision of decimal integer con- 
stants should be taken into account 
when such constants are passed. For 
example; 

CALL ALPHA (6) ; 

ALPHA: PROCEDURE (X) ; 

DCL X FIXED DECIMAL; 

END; 

The above example is incorrect because 
X will be given a default precision, 
while the constant, 6, will be passed 
with precision (1,0). 



DCL i FIXED; 



/*L IS FIXED DECIMAL 
(5,0) REAL 
AUTOMATIC */ 



10. The precision of complex expressions 
is not obvious. For example, the pre- 
cision of 1 + II is (2,0) t that is, 
the precision follows the rules for 
expression evaluation. 

11. When a procedure contains more than 
one entry point, with different param- 
eter lists on each entry, make sure 
that no references are made to parame- 
ters other than those associated with 
the point at which control entered the 
procedure. For example; 
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A: PROCEDURE <P # Q) ; 

P=Q+8,- RETURN? 
B: ENTRY (R,S); 

R=P+S; /*THE REFERENCE TO P 
IS AN ERROR*/ 

END; 

12. Based storage is allocated in terms of 
doublewordsj therefore, even for the 
smallest item, at least eight fcytes 
are required. (I) 

13. The variable used in the REFER option 
must be referred to unambiguously. 
For example: 

DCL 1 A, 

2 Y FIXED BIN, 
2 Z FLOAT, 
1 B, 

2 Y FIXED BIN 

2 T(1:N REFER(B.Y) ) ,• 

In any references to this declaration, 
Y must be fully qualified to prevent a 
possible ambiguity. 

14. A pointer qualifier (explicit or 
implicit) may not be based or 
subscripted. CI) 

15. Conflicting contextual declarations 
roust be avoided. P is often used as 
the name of a pointer and it must not 
then assume by default the characteri- 
stics of another data type. For 
example : 

B BASED (P) , 



initialize the variable, or it can 
occur as a result of the variable hav- 
ing been set in one of the following 
ways: 



by the use of the UNSPEC 
pseudo- variable 



b. by RECORD-oriented input 

c. by overlay defining a picture on a 
character string, with subsequent 
assignment to the character string 
and then access tc the picture 

d. by passing as an argument a vari- 
able assigned in a different pro- 
cedure, without matching the 
attributes of the parameter. 

Failure to initialize a variable will 
result in the variable having an 
unpredictable value at execution time. 
Do not assume this value to be zero. 

Failure to initialize a subscript can 
be detected by checking for subscripts 
out of range, when debugging the 
program. 

Any attempt to write out a variable or 
array that has not been initialized 
may well cause a data interruption to 
occur. For example: 

DCL A(10) FIXED; 

A(l)=10; 

PUT LIST (A) ; 



P AUTO, 



To avoid the data interruption, the 
array should be initialized before the 
assignment statement, thus: 



A=0; 



P is first contextually declared to be 
a pointer and then, by default, to be 
FLOAT DECIMAL. 

16. BASED variables cannot be used as 
arguments or parameters. (I) 

17. Offsets must be declared with a level 
1 unsubscripted based area. 

Assignments and Initialization 

1. When a variable is accessed, it is 

assumed to have a value which has been 
previously assigned to it and which is 
consistent with the attributes of the^ 
variable. If this assumption is inco- 
rrect, either the program will proceed 
with incorrect data or a program 
interruption will occur. Such a 
situation can result from failure to 



Note that this problem can also occur 
as a result of CHECK system action for 
an uninitialized array. If the CHECK 
condition were enabled for the array 
in the above example, and system 
action were taken, the results, and 
the way in which the program ter- 
minates, would be unpredictable. The 
same problem arises when PUT DATA is 
used. 

Note the distinction between = (as- 
signment) and = (comparison). The 
statement 

A=B=C; 

means "compare B with C and assign the 
result (either ^•B or "O'B) to A, 
performing type conversion is 
necessary. " 
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4. Assignments that involve conversions 
should be avoided if possible. 

5. In the case of initialization of or 
assignment to a fixed length string: 
if the assigned value is shorter than 
the string, it is extended on the 
right with blanks (for a character 
string) or zeros (for bit strings). 
For example: 

DCL A CHARC6) , 

B CHAR (3) 1NITCCR - ) ; 
A=B; 

After the execution of the above aLi- 
tements, B would contain CRt, and A 
would contain CRbfcbb. 

6. It is not possible to assign a cross 
section of an array of structures in a 
single statement; the whole of an 
array of structures, or a single ele- 
ment may be referenced, but not a 
cross section- (I) 

7. When SIZE is disabled, the result, of 
an assignment which would have raised 
SIZE is unpredictable: 

FIXED BINARY: The result of an as- 
signment here -— which includes, for 
instance, source language assignments 
and the conversions implied by parame- 
ter matching — may be to raise 
FIXEDOVERFLOW. 

FIXED DECIMAL: Truncation to the 
nearest byte may cccur, without raid- 
ing an interruption- If the ran get 
precision is even, an extra digit may 
be inserted in the high-order byte. 



Arithmetic and Logical Operation s 

1. The rules for expression evaluation 

should be carefully noted, with parti- 
cular reference to priority of opera- 
tions. The following examples show * 
the kind of mistake that can occur: 

X>Y|Z is not equivalent to X>Y| X>Z 
but is equivalent to (X>Y) |Z 

X>Y>Z is not equivalent to X>Y&X>Z 
but is equivalent to (X>Y)>Z 

The clause IF A=B[ |C is equivalent 
to IF A=(B||C),not to IF (A=B)||C 

All operation sequences of equal 
priority are evaluated left to right, 
except for **, prefix + , prefix - , and 
t f which are evaluated right to left. 
Thus, the statement 

A=B**-C**D; 



is equivalent to 



A=B**(-(C**D)) ; 

The normal use of parentheses is to 
modify the rules of priority; however, 
it may be convenient to use redundant 
parentheses as a safeguard or tc 
clarify the operation. 

2. Conversion is governed by comprehen- 
sive rules which must be thoroughly 
understood if unnecessary trouble is 
to be avoided. Some examples of the 
effect of conversion follow. 

a. DECIMAL FIXED to BINARY FIXED can 
cause unexpected results if frac- 
tions are involved: 

DCL I FIXED BIN (31, 5) INITC1); 
I = I+.l; 

The value of I is now 1.06 25. 
This is because .1 is converted to 
FIXED BINARY(S,4), so that the 
nearest binary approximation is 
0.0001B (no rounding occurs). The 
decimal equivalent of this is 
.0625. A better result would have 
been achieved by specifying .1000 
in place of .1. (See alsc item f. 
below. ) 

b. If arithmetic is performed on 
character string data, the inter- 
mediate results are held in the 
maximum precision: 

DCL A CHAR ( 6 ) IN IT ( • 1 2 3 . 4 5 ' ) ; 
DCL B FIXED (5, 2) ; 
B=A; /*B HAS VALUE 123.45*/ 
B=A+A; /*B HAS VALUE 246.00*/ 

c. The rules for arithmetic to bit 
string conversion affect assign- 
ment to a bit string from a decim- 
al constant: 

DCL A BITO ) , 
D BIT (5) ; 
A=l; /*A HAS VALUE f f B*/ 
D=l; /*D HAS VALUE • 00010 f B*/ 
D='B,« /*D HAS VALUE 'lOOOO'B*/ 
IF A=I THEN GO TO Y; 
ELSE GO TO X; 

The branch will be to X, because 
the assignment to A resulted in 
the following sequence of actions: 

(1) The decimal constant, 1, is 

assumed to be FIXED DECIMAL (1, 
0) and is assigned to tem- 
porary storage with the attri- 
butes FIXED BINARY (4, Q) # tak- 
ing the value ' 0001 f B; 
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(2) This value is now treated as a 
bit string of length (4), so 
that it becomes • OQOl/B; 

(3) The resultant bit string is 
assigned to A. Since A has a 
declared length of 1, and the 
value to be assigned has 
acquired a length of 4, trun- 
cation occurs at the right, 
and A has a final value of 
'O'B. 

To perform the comparison opera- 
tion in the IF statement, ' O'B and 
1 are converted to FIXED BINARY 
and compared arithmetically- They 
are unequal, giving a result of 
"false" for the relationship A=l. 

In the first assignment to D f a 
sequence of actions similar to 
that described for A takes place, 
except that the value is extended 
at the right with a zero, because 
D has a declared length that is 1 
greater than that of the value to 
be assigned. 

d. Assignment of arithmetic values to 
character strings involves conver- 
sion according to the rules for 
LIST-directed output. 

Example 1 

DCL A CHAR (4), 
B CHAR (7) ; 
A= , i ; /*A HAS VALUE , 0tbb , *Z 
A=0; /*A HAS VALUE , bbbO , *Z 
B=1234567; /*B HAS VALUE 

Note : The three blanks are neces- 
sary to allow for the possibility 
of a minus sign and/or a decimal 
or binary point, with provision 
for a single leading zero before 
the point. 

Example 2 

DCL CTLNO CHAR (8 > INITIO"); 
DO 1=1 TO 100? 

CTLNO=CTLNO+l; 



END; 

In this example, a conversion 
error occurs because of the fol- 
lowing sequence of actions: 

(1) The initial value of CTLNO, 
that is, ' Obbbbbbb* , is con- 
verted to FIXED DECIMAL(5,0) 
for the addition, gxving a 
temporary value of 00000. 



Item 

1 

3 
1/3 

25 
25+1/3 



(2) The decimal constant, 1, 

assumed to be FIXED DECIMAL 
(1,0), is added; in accordance 
with the rules for addition, 
the precision of the result is 
(6,0), giving a value of 
000001. 



13) This value is now converted to 
a character string of length 
9, value •bbbbbbbbl', in pre- 
paration for the assignment 
back to CTLNO. 

(*4) Because CTLNO has a length of 
8, the assignment causes trun- 
cation at the right; thus, 
CTLNO has a final value that 
consists entirely of blanks. 
This value cannot be success- 
fully converted to arithmetic 
type for the second iteration 
of the loop. 

FIXED division can result in unex- 
pected overflows or truncation. 
For example, the expression 

25+1/3 

would yield a yalue of 5. 3 3... 3. 
To obtain a result of 25. 33... 3 f 
it would be necessary to write 

25+01/3 

The explanation is that constants 
have the precision and scale fac- 
tor with which they are written, 
while FIXED division results in a 
value of maximum implementation- 
defined precision. The results of 
the two evaluations are reached as 
follows: 



01 
3 
01/3 
25 
25+01/3 
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Checking of a picture is performed 
only on assignment into the pic- 
ture variable: 

DCL A PIC'999999' , 

B CHARC6) DEF A, 

C CHAR (6) ; 
B= , ABCDEF f ; 
C=A; /*WILL NOT RAISE CONV 

CONDITION*/ 
A=C; /*WILL RAISE CONV*/ 

Note also (A, B, C as declared 
above) : 

A=123456; /*A HAS VALUE 123456*/ 
/*B HAS VALUE 

•123456 1 */ 
C=123456; /*C HAS VALUE 

, tfcfcl23'*/ 
C=A; /*C HAS VALUE , 123456 f */ 

A decimal fixed-point element with 
a declared even precision (P,Q> 
may have an effective precision of 
(P+1,Q), as the high-order byte 
may not be nonzero. The SIZE con- 
dition can be used to eliminate 
this effect: 

DCL (A,B,C) FIXED DECINAL 
(6,0); 

ON SIZE; 



(SIZE) : A = B + C; 

This ensures that the high-order 
byte of A is zero after the 

assignment. 



DQ-groups 
1. 



3. 



The scope of a condition prefix ap- 
plied to a DO statement is limited to 
execution of the statement itself; it 
does not apply to execution of the 
entire group. 

An iterative DO group is not executed 
if the terminating condition is satis- 
fied at initialization: 

1=6; 

DO J = I TO 4; 
X=X+J; 

END; 

X is not altered by this group, since 
BY 1 is implied. Iterations can step 
backwards, and if BY -1 had been spe- 
cified, three iterations would have 
taken place. 

Expressions in a DO statement are 
assigned to temporaries with the same 



characteristics as the expression, not 
the variable. For example: 



CCL A DECIMAL FIXED(5,Q); 
A=10; 
DO 1=1 TO A/2; 



END; 

This loop will not be executed, 
because A/2 has decimal precision 
(15,10), which, on conversion to 
binary (for comparison with I) , becom- 
es binary (31, 34) . 

Five iterations would result if the DO 
statement were replaced by 

ITEMP=A/2; 

CO 1=1 TO ITEMP; 

4. DO-groups cannot be used as ON-units. 

5. Upper and lower bounds of iterative 
DO-groups are computed once only, even 
if the variables involved are reas- 
signed within the group. This applies 
also to the BY expression. 

Any new values assigned to the 
variables involved would take effect 
only if the DO-GROUP WAS STARTED 
AGAIN. 

6. In a DO~group with both a control 
variable and a WHILE clause, the eval- 
uation and testing of the WHILE expre- 
ssion is carried out only after deter- 
mination (from the value of the con- 
trol variable) that iteration may be 
performed. For example, the following 
group would be executed at most once: 

DC 1=1 WHILE (X>Y) ; 



END; 

7. I is frequently used as the control 
variaLie in a DO-group, for example; 

CO 1=1 TO 10; 

Within the scope of this implicit 
declaration, I might be contextually 
declared as a pointer, for example: 

CCI X BASED (I) ; 

The two statements are in conflict and 
will produce a diagnostic message. 
When I is a pointer variable, it can 
only be used in a DO-group in one of 
the following ways: 
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DCL (P, IA, IB, IC) POINTER; 



DCL (A r B,C> (10 r 10>; 



DO P=IA,IB,IC; 



2. DCL (P, IA) POINTER; 



CO 1=1 TO 10? 

DO J=l TO 10; 

A(I, J)=B(I, J)*C(I r J); 

END j END; 



DO WHILE (P=IA); 



Data Aggregates 

1. Array arithmetic should be thought of 
as a convenient way of specifying an 
iterative computation. For example: 



DCL A (10 , 20) ; 

A=A/A(l f 1) ; 
has the same effect as 
DCL A(10,20) ; 



DO 1=1 TO 10; 
DO J=l TO 20; 
A(I f J>=A(I,J)/A(l f l) ; 
END; END; 

Note that the effect is to change the 
value of A(l,l) only, since the first 
iteration would produce a value of 1 
for A (1,1). If the user wanted to 
divide each element of A by the origi- 
nal value of A(l,l), he could write 

B=AC181) ; 
A=A/B; 

or alternatively, 

DCL A(10,20), 
B(10 f 20> ; 



Strings 

1. Assignments made to a varying string 
by ireans of the SUBSTR pseudo- variable 
do not set the length of the string. 

A varying string initially has an 
undefined length, so that if all assi- 
gnments to the string are made using 
the SUBSTR pseudo-variable, the string 
still has an undefined length and can- 
not be successfully assigned to anoth- 
er variable or written out. 

2. The user roust ensure that the lengths 
of intermediate results of string 
expressions do not exceed 32767 bytes. 
This applies particularly to variable 
string lengths, as there is no object- 
time length checking. CI) 

Functions and Pseudo-Variables 

1. When UNSPEC is used as a pseudo- 
variable, the expression on the right 
is converted to a bit string. Conse- 
quently, the expression must not be 
invalid for such conversion; for 
example, if the expression is a 
character string containing characters 
other than or 1 , a conversion error 
will result. 

Qn-Conditions and On-Units 

1. Note the correct positioning cf the ON 
statement. If the specified action is 
to apply when the named condition is 
raised by a given statement, the ON 
statement must be executed before that 
statement. The statements: 

GET FILE CACCTS) LIST (A,B,C>; 
ON TRANSMIT (ACCTS) GO TO TRERR ; 



B=A/A(1,1); 

2. Note the effect of array 
mu It i pli cat i on : 

DCL (A,B,C) (10,10); 



would result 
being raised 
mission error 
operation, an 
would not be 
previous ON s 
therroore, the 
executed afte 
GET statement 



in the ERROR condition 
in the event of a trans- 

during the first GET 
d the required branch 
taken (assuming that no 
tatement applies). Fur- 

ON statement would be 
r each execution of the 



A=B*C; 

This does not effect matrix multipli- 
cation; it is equivalent to: 



An on-unit cannot be entered by means 
of a GOTO statement. To execute an 
on-unit deliberately, the SIGNAL sta- 
tement can be used. 
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3. CONVERSION on-units entered as a 
result of an invalid conversion (as 
opposed to SIGNAL) should either 
change the invalid character (by means 
of the ONSOURCE or ONCHAR pseudo- 
variable) # or else terminate with a 
GOTO statement. Otherwise, the system 
will print a message and raise the 
ERROR condition. 

4. At normal exit from an AREA on-unit, 
the standard system action is to try 
again to make the allocation. Unless 
the on-unit makes the allocation poss- 
ible, therefore, the on-unit will be 
entered again and an indefinite loop 
will be created. To avoid this, the 
amount allocated should be modified in 
the on-unit; for example, the EMPTY 
built-in function could be used, or a 
pointer variable could be changed. 

Input/Output 

1. The UNDEFINEDFILE condition may be 
raised if a STREAM file is reopened 
with attributes or options that con- 
flict with attributes, options, or 
parameters previously specified for • 
it. For example, if a file originally 
opened with a LINESIZE of 100 is sub- 
sequently reopened with a LINESIZE of 
131, the UNDEFINEDFILE condition will 
be raised if the DCB sutoperand 
BLKSIZE is not specified in the DDEF 
command, or if it is specified as less 
than 132. Difficulties of this nature 
can be avoided by the use of different 
file names, or by using the same file 
name with different TITLE option 
specifications. (I) 

2. The UNDEFINEDFILE condition is raised 
not only by conflicting language 
attributes (such as DIRECT with 
PRINT), but also by the following: 

a. Block size smaller than record 
size. 



h. 



1. 



resulting in KEYLEN+RKP exceeding 

LRECL. 



Specifying a format- V logical rec- 
ord length of less than 18 bytes 
for STREAM data sets. 

Specifying, for format-F blocked 
records, a block size that is not 
an integral multiple of the record 
size. 

Specifying, for tormat-V records, 
a logical record length that is 
not at least four bytes smaller 
than the specified block size. 

Attempting to open a file with the 
UNBUFFERED attribute for blocked 
records. 

Attempting to use blocked reccrds 
in the system input streair with an 
UNBUFFERED file. The default rec- 
ord format for the system input 
stream is FB- format. Since this 
stream is not checked on input, 
the presence of FB- format records 
will not be detected until an 
attempt is made to open the file, 
when UNDEFINEDFILE will be raised. 



Note: 



If the UNDEFINEDFILE condition 



is raised because either the key 
length or the block size is not speci- 
fied, a subsequent attempt to open the 
file will not raise this condition 
again. 

3. If a file is to be used for both input 
and output, it must not be declared 
with either the INPUT or the OUTPUT 
attribute. The required option can be 
specified on the OPEN STATEMENT. 
There must be no conflict between file 
.attributes specified in the declara- 
tion and those specified by the OPEN 
statement . 



b. LINESIZE exceeding the permitted 4. 
maximum. 

c. Format-U records specified for 
INDEXED organization. 

d. KEYLEN not specified for creation 

of INDEXED data sets. 5. 

e. Attempting to open an INDEXED data 
set for DIRECT OUTPUT. 

f. Attempting to open a CONSECUTIVE 

data set with DIRECT or KEYED 6. 

attributes. 

g. Specifying an RKP option, for an 
INDEXED data set, with a value 



Input/output lists must be surrounded 
by a pair of parentheses,- so must 
iteration lists. Therefore, twc pairs 
of outer parentheses are required in 

GET LIST (CAQ) DO 1=1 TO N)); 

Note that the file must have the KEYED 
attribute if the KEY, KEYFROM, or 
KEYTO options are to be used in any 
input/output statement referring to 
that file. 

The standard file names SYSIN and SYS- 
PRINT are implicit only in GET and PUT 
statements. Any other reference, such 
as those in ON statements, must be 
explicit. 



► 178 



7. PAGESIZE and LINESIZE are not file 
attributes, that is, they cannot be 
included in a DECLARE statement for 
the file; they are options on the OPEN 
statement . 

8. When an edit-directed data list is 
exhausted, no further forrrat items 
will be processed, even if the next 
format item does not require a match- 
ing data item. For example: 

DCL A FIXED* 5> , 

B FIXED(5,2> ; 
GET EDIT (A, B) 

(F(5) f F(5 r 2> ,X(70>); 

The XC70) format item will not be pro- 
cessed. To read a following card with 
data in the first ten columns only, 
the SKIP option can be used: 

GET EDIT (A,B) (F(5), F(5,2>) 

SKIP; 

9. The number of data items represented 
by an array or structure name appear- 
ing in a data list is equal to the 
number of scalar elements in the array 
or structure; thus, if more than one 
format item appears in the format 
list, successive elements will be 
matched with successive format items. 
For example: 

DCL 1 A, 

2 B CHAR (5), 
i C FIXED15, 2) ; 



PUT EDIT (A) CA(S) ,F<5,2)> ; 

B will be matched with the A (5) item, 
and C will be matched with the F(5,2) 
item. 

10. Arrays are transmitted in row major 
order (e.g., A(l,l), All, 2), A<1, 3), 
... AC2,1) , ... etc. ) 

11. Strings used as input data for GET 
DATA and GET LIST must be enclosed in 
apostrophes. 

12. The 48-character representation of a 
semicoln (,.) is not recognized as 
asemicolon if it appears in a DATA- 
directed input stream; the 11-8-6 
punch must be used. (I) 

13. The user must be aware of two limita- 
tions of PUT DATA; (i.e., no data 
list). First, its use with an ON sta- 
tement is restricted because the data 
known to PUT DATA would b^ the data 
known at the point of the on-unit. 
Second, and more serious, the data 



will be put out as normal data- 
directed output, which means that any 
unallocated or unassigned data pray 
raise a CONVERSION or other condition. 

If the on-unit 

ON ERROR PUT DATA; 

is used in an outer block, it must be 
remembered that variables in inner 
blocks are not known and therefore 
will not be dumped. It would be a 
good practice, therefore, to repeat 
the on-unit in all inner blocks during 
debugging . 



during execu- 
tatement, and 
in an ERROR on- 

recursively 
t until no more 
e operation, 
steful of 
out, the ERROR 
ed off once it 

of: 



If an error does occur 
tion of the PUT DATA s 
this statement is with 
unit, the program will 
enter the ERROR on-uni 
storage remains for th 
Since this could be wa 
machine time and print 
on-unit should be turn 
is activated. Instead 

ON ERROR PUT DATA; 

better code would be: 



ON ERROR BEGIN; 

ON ERROR SYSTEM; 
PUT DATA; 

END; 

When PUT DATA is used without a data- 
list every variable known at that 
point in the program is transmitted in 
data-directed output format to the 
specified file. Users of this facili- 
ty, however, should note that: 

a. Uninitialized decimal fixed-point 
data may raise the CONVERSION con-™ 

dition or a data interruption. 

b. Unallocated controlled data will 
cause arbitrary values to be 
printed and, in the case cf deciro- 
al fixed-point, may raise the CON- 
VERSION condition or a data 
interruption. 

14. Use of locate mode I/O . A pointer set 
in READ SET or LOCATE SET may not be 
valid beyond the next operation on the 
file, or beyond a CLOSE statement. In 
OUTPUT files, WRITE and LOCATE state- 
ments can be freely mixed. 

For UPDATE files, the REWRITE state- 
ment with no options must be used if 
it is required to rewrite an updated 
record. The result of this REWRITE is 
always to rewrite the contents of the 
last buffer onto the data set. 
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For example: 

3 READ FILE (F) SET (P) ; 



the file is closed, the record is 
not transmitted , and the embedded 
key is overwritten with the KEY- 
FRCK string , and the record is 
transmitted. 



P->R 



S; 



7 REWRITE FILE (F) ; 



11 READ FILE (F) INTO (X) ; 



Thus the condition may be raised 
by a CLOSE statement or by an END 
statement that causes implicit: 
closing. Until the error is 
corrected, the record cannot be 
transmitted and no further opera- 
tion can be carried out on the 
file. 



15 REWRITE FILE (F) ; 



19 REWRITE FILE (F) FROM (X); 
Notes : 

Statement 7 will rewrite a record 

updated in the buffer. 

Statement 15 will only rewrite 
exactly what was read, i.e., it 
will not change the data set at 
all. 

Statement 19 will raise ERROR, 

since there is no preceding READ 
statement. 

There are two cases where it is not 
possible to check for the KEY condi- 
tion on a LOCATE statement until tran- 
smission of a record is attempted. 
(This will generally occur on execu- 
tion of the next PL/I output statement 
for this file.) 

These are: 

When the embedded key differs from 
the KEYFROM in a VISA*> file. 

If this LOCATE statement is to 
transmit the last record before 



15. Allocation and freeing of based 

variables: If a reference is made, at 
object time, to a BASED variable that 
has not been allocated storage, an 
unpredictable interruption (protec- 
tion, addressing or specification) may 
occur. 



16. Areas, pointers, offsets and struc- 
tures containing any of these cannot 
be used with STREAM I/O. PUT DATA 
cannot be used with BASED variables. 

When a based variable is freed, the 
associated pointer no longer contains 
useful information. This pointer can 
only be used again if: 

a. It is reallocated with the same or 
another based variable, or, 

b. A value is assigned to it from an 
offset or another pointer 

A based variable allocated in an 
area must be freed in that area. 
For example: 

DCI A AREA, B BASED (X) ; 
ALLOCATE B IN (A) ; 



FREE B; 

FREE B IN (A) ; 



/* ILLEGAL */ 
/* LEGAL */ 
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SECTION 1: SYNTAX NOTATION 



Throughout this publication, wherever a 
PL/I statement -- or some other combination 
of elements -- is discussed, the manner of 
writing that statement or phrase is illus- 
trated with a uniform system of notation. 



This notation is not a part of PL/I? it 
is a standardized notation that may be used 
to describe the syntax -- or construction 
-- of any programming language. It pro- 
vides a brief but precise explanation of 
the general patterns that the language per- 
mits. It does not describe the meaning of 
the language elements, merely their struc- 
ture ; that is, it indicates the order in 
which the elements may (or must) appear, 
the punctuation that is required, and the 
options that are allowed. 

The following rules explain the use of 
this notation for any programming language; 
only the examples apply specifically to 
PL/ 1: 

1. A notation variable is the name of a 
general class of elements in the pro- 
gramming language. A notation vari- 
able must consist of: 

a. Lower-case letters, decimal 
digits, and hyphens and must begin 
with a letter. 

b. A combination of lower-case and 
upper-case letters. There must be 
one portion in all lower-case let- 
ters and one portion in all upper- 
case letters, and the two portions 
must be separated by a hyphen. 

All such variables used are defined in 
the manual either syntactically, using 
this notation, or are defined 
semantically. 

Examples : 

a. digit. This denotes the occur- 
rence of a digit, which may be 
through 9 inclusive. 

b. file-name. This denotes the 
occurrence of the notation vari- 
able named file name. An explana- 
tion of file name is given else- 
where in the manual. 

c. DO-statement. This denotes the 
occurrence of a DO statement. The 
upper-case letters arc used to 
indicate a language keyword. 



A notatio n constant denotes the liter- 
al occurrence of the characters repre- 
sented. A notation constant consists 
either of all capital letters or of a 
special character. 

Example: 

DECLARE identifier FIXED; 

This denotes the literal occurrence of 
the word DECLARE followed by the nota- 
tion variable "identifier," which is 
defined elsewhere, followed by the 
literal occurrence of the word FIXED 
followed by the literal occurrence of 
the semicolon (;>. 

The term "syntactic unit," which is 
used in subsequent rules, is defined 
as one of the following: 

a. A single notation variable or 
notation constant. 

b. Any collection of notation 
variables, notation constants, 
syntax-language symbols, and key- 
words surrounded by braces or 
brackets. 



Braces {} are used to denote grouping 
of more than one element into a syn- 
tactic unit. 



Example: 



identifier 



FIXED 
FLOAT 



The vertical stacking of syntactic 
units indicates that a choice is to be 
made. The above example indicates 
that the variable "identifier" must be 
followed by the literal occurrence of 
either the word FIXED or the word 
FLOAT. 



The vertical stroke | indicates that a 
choice is to be made. 

Example: 

identifier {FIXED) FLOAT} 

This has exactly the same meaning as 
the above example. Both methods are 
used in this manual to display 
alternatives. 
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Square brackets { 1 
Anything enclosed in 
appear one time or m 
all. Brackets can s 
ai purpose of delimi 
unit. Vertical stac 
ets means that no mo 
stacked syntactic un 

Example : 



denote options. 

brackets may 
ay not appear at 
erve the addition- 
ting a syntactic 
king within brack- 
re than one of the 
its can appear. 



{ [lower- bound : 1 upper™ bound} | * 

This denotes the occurrence of either 
a literal asterisk or the variable 
" upper- bound , " but not both. If 
"upper- bound" appears, it can option- 
ally be preceded by the syntactic unit 
composed of the variable "lower-bound" 
and the literal colon. 

Three dots . . . denote the occurrence 
of the immediately preceding syntactic 
unit one or more times in succession. 

Example : 

[digit] ... 



8. 



The variable "digit" may or may not 
occur since it is surrounded by brack- 
ets. If it does occur, it may be 
repeated one or more times. 



Underlining is used to denote an ele- 
ment in the language being described 
when there is conflict between this 
element and one in the syntax 
language. 



Example: 



operand C£|J_} operand 



This denotes that the two occurrences 
of the variable "operand" are 
separated by either an "and" (£) or an 
"or" C|). The constant | is under- 
lined in order to distinguish the "or" 
symbol in the PL/I language from the 
"or" symbols in the syntax language. 
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SECTION 2: CHARACTER SETS WI TH EBCDIC AND CARD-PUNCH CODES* 



60 -CHARACTER SET 



Character 
blank 

< 

C 

♦ 

I 

s 

$ 

♦ 



/ 

f 

> 

? 

n 



A 

B 
C 
D 
E 
F 
G 
H 
I 
J 
K 
L 
M 



Card-Punch 


8- Bit Code 


no punches 


0100 


0000 


12-8-3 


0100 


1011 


12-8-11 


0100 


1100 


12-8-5 


0100 


1101 


12-8-6 


0100 


1110 


12-8-7 


0100 


1111 


12 


0101 


0000 


11-8-3 


0101 


1011 


11-8-4 


0101 


1100 


11-8-5 


0101 


1101 


11-8-6 


0101 


1110 


11-8-7 


0101 


1111 


11 


0110 


0000 


0-1 


0110 


0001 


0-8-3 


0110 


1011 


0-8-4 


0110 


1100 


0-8-5 


0110 


1101 


0-8-6 


0110 


1110 


0-8-7 


0110 


1111 


8-2 


0111 


1010 


8-3 


0111 


1011 


8-1* 


0111 


1100 


8-5 


0111 


1101 


8-6 


0111 


1110 


12-1 


1100 


0001 


12-2 


1100 


0010 


12-3 


1100 


0011 


12-4 


1100 


0100 


12-5 


1100 


0101 


12-6 


1100 


0110 


12-7 


1100 


0111 


12-8 


1100 


1000 


12-9 


1100 


1001 


11-1 


1101 


0001 


11-2 


1101 


0010 


11-3 


1101 


0011 


11-4 


1101 


0100 



Character 

N 
O 
P 

Q 
R 
S 
T 
I) 
V 
W 
X 
Y 
2 

1 
2 
3 
4 
5 
6 
7 
8 
9 



Composite 
Symbols 
<= 

II 

♦ * 

i< 
i> 
i ~ 
>= 
/* 

♦ / 
-> 



Card -Punch 


8-Bit Code 


11-5 


1101 


0101 


11-6 


1101 


0110 


11-7 


1101 


0111 


11-8 


1101 


1000 


11-9 


1101 


1001 


0-2 


1110 


0010 


0-3 


1110 


0011 


0-4 


1110 


0100 


o-s 


1110 


0101 


0-6 


1110 


0110 


0-7 


1110 


0111 


0-8 


1110 


1000 


0-<> 


1110 


1001 





1111 


0000 


1 


1111 


0001 


2 


1111 


0010 


3 


1111 


0011 


4 


1111 


0100 


5 


1111 


0101 


6 


1111 


0110 


7 


1111 


0111 


8 


. 1111 


1000 


9 


1111 


1001 



Card- 


-Punch 




12- 


-8- 


-4, 


8-6 




12- 


-8- 


-7, 


12-8- 


-7 


11- 


-8- 


-4, 


11-8- 


■4 


11- 


-8- 


-7 f 


12-8- 


■4 


11- 


-8- 


"7, 


0-8-6 


» 


11- 


•8- 


-7, 


8-6 




0-f 


]-t 


5, I 


3-6 




o-i, 


11- 


-8-4 




11- 


-8- 


-4, 


0-1 




11. 


( 


)-8- 


-6 





*These card codes are those used by the TSS/360 high-speed card reader. The code varia- 
tions for use with the IBM 1056 Card Reader can be found in IBM System/360 Time Sharing 
System; Terminal User's Guide , GC28-2017. 
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4 8 -CHARACTER SET 



Character 
blank 

C 

# 
> 



A 
B 
C 
D 
E 
F 
G 
H 
I 
J 
K 
L 
M 
N 
O 
P 
Q 
R 
S 
T 
U 
V 
W 
X 
Y 
Z 


1 

2 
3 
4 
5 
6 
7 
8 
9 



Card-Punch 


8-Bit Code 


no punches 


0100 


0000 


12-8-3 


0100 


1011 


12-8-5 


0100 


1101 


12-8-6 


0100 


1110 


11-8-3 


0101 


1011 


11-8-4 


0101 


1100 


11-8-5 


0101 


1101 


11 


0110 


0000 


0-1 


0110 


0001 


0-8-3 


0110 


1011 


8-5 


0111 


1101 


8-6 


0111 


1110 


12-1 


1100 


0001 


12-2 


1100 


0010 


12-3 


1100 


0011 


12-4 


1100 


0100 


12-5 


1100 


0101 


12-6 


1100 


0110 


12-7 


1100 


0111 


12-8 


1100 


1000 


12-9 


1100 


1001 


11-1 


1101 


0001 


11-2 


1101 


0010 


11-3 


1101 


0011 


11-4 


1101 


0100 


11-5 


1101 


0101 


11-6 


1101 


0110 


11-7 


1101 


0111 


11-8 


1101 


1000 


11-9 


1101 


1001 


0-2 


1110 


0010 


0-3 


1110 


0011 


0-4 


1110 


0100 


0-5 


1110 


0101 


0-6 


1110 


0110 


0-7 


1110 


0111 


0-8 


1110 


1000 


0-9 


1110 


1001 





1111 


0000 


1 


1111 


0001 


2 


1111 


0010 


3 


1111 


0011 


4 


1111 


0100 


5 


1111 


0101 


6 


1111 


0110 


7 


1111 


0111 


8 


1111 


1000 


9 


1111 


1001 







60- 


Character 


Composite 




Set 




Symbols 


Card Punch 


Equivalent 


• m 


12-8-3, 1.2-8-3 




: 


IE 


11-1, 12-5 




<= 


CAT 


12-3, 12- l f 0-3 




11 


** 


11-8-4, 11-8-4 




#* 


HL 


11-5, 11-3 




i< 


NG 


11-5, 12-7 




i> 


NE 


11-5, 12-5 




1 _ 


// 


0-1, 0-1 




% 


t • 


0-8-3 r 12-8-3 




f 


AND 


12-l f 11-5, 12-4 




& 


GE 


12-7, 12-5 




>= 


.GT 


12-7, 0-3 




> 


LT 


11-3, 0-3 




< 


NOT 


11-5, 11-6, 0-3 




i 


OR 


11-6, 11-9 




1 


/* 


0-1, 11-8-4 




/* 


*/ 


11-8-4, 0-1 




*/ 


PT 


11-7, 0-3 




-> 



Note : When using the 48-character set, the 
following rules should be observed: 



1. ■ The two periods that replace the colon 

must be immediately preceded by a 
blank if the preceding character is a 
period* 

2. The two slashes that replace the per- 
cent symbol must be immediately pre- 
ceded by a blank if the preceding 
character is an asterisk, or iirrnedi- 
ately followed by a blank if the fol- 
lowing character is an asterisk* 

3. The sequence "comma period" represents 
a semicolon except when it occurs in a 
comment or character string f or when 
it is immediately followed by a digit. 

4. When the compiler option CHAR48 is 
specified in the PL1 command for the 
compilation Isee IBM System/360 Time 
Sharing System^ PL/I Programmer's 
Guide ) , 60-character set symbols may 

' be freely intermixed with 48-character 
set symbols and will be accepted by 
the compiler as valid input* 

5* 48-character set "reserved" words 

(e.g., GT # LE f CAT # etc.,) must be pre- 
ceded and followed by a blank or a 
comment. If they are not, the inter- 
pretation by the compiler is undefined 
and may not, therefore, be what the 
user intended. 

A record containing part or all of a 
48-character set reserved word must be 
3 characters or more in length. 
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SECTION 3: KEYWORDS AND KEYWORD ABBREVIATIONS 



Keyword 

ABS(x> 

%ACTIVATE 

ADD(x,y,p£ , q] ) 

ADDRCx) 

ALIGNED 

ALL(X> 

ALLOCATE 

ALLOCATION (x) 

ANY(x) 

AREA 

AREAf (size)] 

ATAN(x[,y]> 

ATAND(x[ f y]> 

ATANH(x) 

AUTOMATIC 

BACKWARDS 

BASED (pointer-variable) 

BEGIN 

BINARY 

BINARY (x[,pt, q] 3) 

BITC length) 

BIT (expressiont, size! ) 

BOOL(x,y,w) 

BUFFERED 

BUFFERS (n) 

BUILTIN 

BY 

BY NAME 

CALL entry- name 

CEIL(x) 

CHAR (express ion t f size] ) 

CHARACTER (length) 

CHECK (name- list) 

CLOSE 

COBOL 

COLUMN (w) 

COMPLETION (event-name) 

COMPLEX 

COMPLEX (a , b) 

CONDITION (name) 

CONJG(x) 

CONSECUTIVE 

CONTROLLED 

CONVERSION 

COPY 

COS(x) 

COSD(x) 

COSH(x) 

COUNT (file-name) 

CTLASA 

CTL360 

DATA 

DATAFIELD 

DATE 

XDEACTIVATE 

DECIMAL 

DECIMALCxt ,p[ ,q] 3 > 

DECLARE 



Abbreviation 
XACT 



AUTO 



BIN 
BIN(xl f p[,qJl) 



BUF 



CHAR (length) 



COL (w) 

CPLX 
CPLX(a f b) 



CTL 
CONV 



Use of Keywor d 
built-in function 
preprocessor statement 
built-in function 
built-in function 
attribute 
built-in function 
statement 
built-in function 
built-in function 
condition 
attribute 
built-in function 
built-in function 
built-in function 
attribute 

attribute, option of OPEN statement 

attribute 

statement 

att r i but e 

built-in function 

attribute 

built-in function 

built-in function 

attribute 

option of ENVIRONMENT attribute 

attribute 

clause of DO statement 

option of the assignment statement 



statement 

built-in 

built-in 

attribute 

condition 

statement 

option of 

format it 

built-in 

data attr 

built-in 

condition 

built-in 

option of 

attribute 

condition 

option of 

built-in 

built-in 

built-in 

built-in 

option of 

option of 



or option of INITIAL attribute 
function 
function 



ENVIRONMENT attribute 
em 

function, pseudo-variable 
ibute 
function f pseudo-variable 

function 
ENVIRONMENT attribute 



GET statement 

function 

function 

function 

function 
ENVIRONMENT attribute 
ENVIRONMENT attribute 



fcDEACT 

DEC 

DEC(xt f pC f q]]) 

DCL 



STREAM I/O transmission mode 

built-in function 

built-in function 

preprocessor statement 

attribute 

built-in function 

statement 
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Keyword 


Abbreviation 


%DECLARE 


%DCL 


DEFINED 


DEF 


DELAY (n) 




DELETE 




DIM(x,n) 




DIRECT 




DISPLAY 




DIVID£Cx,y,p[,q]) 




DO 




%DO 




EDIT 




ELSE 




XELSE 




S4PTY 




END 




%END 




ENDFILE ( file-name) 




ENDPAGE C file-name) 




BWTRY 




ENVIRONMENT 


ENV 


ERFCx) 




ERFCCx) 




ERROR 




EVENT 




EXCLOS1VE 


EXCL 


EXIT 




EXP C x) 




EXTERNAL 


EXT 


F ( block- size t ,record- 


-size)) 


FILE 




FiLEC file-name) 




FINISH 




FIXED 




FIXED(x[,p[,q]]> 




FIXEDOVERFLOW 


FOFL 


FLOAT 




FLOAT Cx[, pi) 




FLOOR tx) 




FORMAT (format-list) 




FREE 




FROM (variable) 




GENERIC 




GET 




GO TO 


GOTO 


XGO TO 


%GOTO 


HBOOND(x,h) 




HIGH(i) 




IF 




%IF 




IGNORE (n) 




IMAG(x) 




IN 




%1NCLUDE 




INDEX (string, config) 




INDEXED 




INITIAL 


INIT 


INPUT 




INTERNAL 


INT 


INTO (variable) 




1RREDOCIBLE 


IRRED 



Use of Keyword 

preprocessor statement 

attribute 

statement 

statement 

built-in function 

attribute 

statement 

built-in function 

statement 

preprocessor statement 

STREAM I/O transmission mode 

clause of IF statement 

clause of %IF statement 

built-in function 

statement 

preprocessor statement 

condition 

condit ion 

attribute or statement 

attribute 

built-in function 

built-in function 

condition 

option of DISPLAY, READ, WRITE, REWRITE, 

and DELETE statements 
attribute 
statement 
built-in function 
attribute 

option of ENVIRONMENT attribute 
attribute 

option of GET and PUT statements, 

specification of RECORD I/O statements 

condition 
attribute 

built-in function 

condition 

attribute 

built-in function 

built-in function 

statement 

statement 

option of WRITE or REWRITE statements 

attribute 
statement 
statement 

preprocessor statement 

built-in function 
built-in function 

statement 

preprocessor statement 

option of READ statement 

built-in function, pseudo- variable 

option of ALLOCATE and FREE statements 

preprocessor statement 

built-in function 

option of ENVIRONMENT attribute 

attribute 

attribute, option of the OPEN statement 

attribute 

option of READ statement 

attribute 
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Keyword 

KEY (file-name) 

KEY(x) 

KEYED 
KEYFROM(x) 
KEYTO (variable) 

LABEL 

LENGTH (string) 

LBOUND(x,n) 

LEAVE 

LIKE 

LINE(w) 

LINENO (file- name) 

LINESIZE(w) 

LIST 

LOCATE 

LOG(x) 

LOG2(x) 

LOG10 (x) 

LOW(i) 

MAIN 

MAX(x :L ,X a . . .X n ) 

MIN(x ± ,x a . . .X n ) 

MOD(x if x a ) 

MULTIPLY (x ± , x a , p£ , g] ) 

NAME (file- name) 
NCP(n) 



NOCHECK 

NOCONVERSION 

NOFIXEDOVERFLOW 

NOOVERFLOW 

NOSIZE 

NOSTRING RANGE 

NOSUBSCRI PTRANGE 

NOUNDERFLOW 

NOZERODIVIDE 

NULL 
NULLO 

OFFSET (area-name) 

ON 

ONCHAR 

ONCOUNT 

ONCODE 

ONFILE 

ONKEY 

ONLOC 

ONSOURCE 

OPEN 

OPTIONS (list) 

ORDER 

OUTPUT 

OVERFLOW 



Abbreviation 



NOCONV 
NOFOFL 
NOOFL 



NOSUBRG 

NOUFL 

NOZDIV 



Use of Keyword 

condition 

Option of READ* DELETE, and REWRITE 

statements 
attribute , option of OPEN statement 
option of WRITE statement 
option of READ statement 

attribute 

built-in function 

built-in function 

option of ENVIRONMENT attribute 

attribute 

format item, option of PUT statement 

built-in function 

option of OPEN statement 

STREAM I/O transmission mode 

statement 

built-in function 

built-in function 

built-in function 

built-in function 

option of PROCEDURE statement 
built-in function 
built-in function 
built-in function 

built-in function 

condition 

option of ENVIRONMENT attribute 

(valid only for CONSECUTIVE SEQUENTIAL 

UNBUFFERED files) 

condition prefix identifier 

(disables CHECK) 
condition prefix identifier 

(disables CONVERSION) 
condition prefix identifier 

(disables FIXEDOVERFLOW) 
condition prefix identifier 

(disables OVERFLOW) 
condition prefix identifier 

(disable SIZE) 
condition prefix identifier 

(disables STRINGRANGE) 
condition prefix identifier 

(disables SUBSCRI PTRANGE) 
condition prefix identifier 

(disables UNDERFLOW) 
condition prefix identifier 

(disables ZERODIVIDE) 
built-in function 
built-in function 



pseu do- variable 



OFL 



attribute . 

statement 

built-in function, 

built-in function 

built-in function 

built-in function 

built-in function 

built-in function 

built-in function, pseudo- variable 

statement 

option of PROCEDURE statement 

option of PROCEDURE and BEGIN statements 

attribute, option of the OPEN statement 

condition 
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Keyword 
I PAGE 

PAGESIZE(w) 

PICTURE 

POINTER 

POLY(a # x) 

POSITJONCi) 

PREC IS ION (x, p [ , q] ) 

PRINT 

PROCEDURE 

XPROCEDURE 

PROD(x) 

PUT 



Abbreviation 



PIC 
PTR 

POS(i) 
PREC(x,p£,ql) 

PROC 
%PROC 



Use of Keyword 

format item, option of PUT statement 

option of the OPEN statement 

attribute 

attribute 

built-in function 

attribute 

built-in function 

attribute, option of OPEN statement 

statement 

preprocessor statement 

built-in function 

statement 



READ 
REAL 
REALCx) 
RECORD 

RECURSIVE 

REDUCIBLE RED 

REENTRANT 

REFER 

REORDER 

REPEAT (string , i) 

REPLY Cc) 

RETURN 

RETURNS 

REVERT 
REWIND 
REWRITE ' 
ROUND (x,n> 

SEQUENTIAL SEQL 

SET (pointer- variable) 

SIGN(x) 

SIGNAL 

SINCx) 

SIND(x) 

SINH(x) 

SIZE 

SKIP! Cx>] 

SNAP 

SQRTCx) 

STATIC 

STATUS (event -name) 

STOP 

STREAM 

STRING (X) 

STRINGRANGE STRG 

STRING (string-name ) 

iSUB 

SUBSCRIPTRANGE SUBRG 

SUBSTR (string, i£, jl) 

SUM(x) 

SYSIN 

SYSPRINT 

SYSTEM 

TAN(x) 

TAND(x) 

TANH(x) 

THEN 

%THEN 



statement 

attribute 

built-in function, pseud o- variable 

file attribute, option 

of OPEN statement, condition 

option of PROCEDURE statement 

attribute 

option of PROCEDURE statement 

option of BASED attribute 

option of PROCEDURE and BEGIN statements 

built-in function 

option of DISPLAY statement 

statement 

attribute, option of PROCEDURE and ENTRY 

statements 
statement 

option of ENVIRONMENT attribute 
statement 
built-in function 

attribute 

option of ALLOCATE, LOCATE, and 

READ statements 
built-in function 
statement 
built-in function 
built-in function 
built-in function 
condition 
format item, option of GET and 

PUT statements 
option of ON statement 
built-in function 
attribute 

built-in function, peeudo -variable 
statement 

attribute, option of OPEN statement 
built-in function, pseudo- variable 
condition 

option of GET and PUT statements 
dummy variable of DEFINED attribute 
condition 

built-in function, pseudo-variable 
built-in function 

name of standard system input file 
name of standard system output file 
option of the ON statement 

built-in function 
built-in function 
built-in function 
clause of IF statement 
clause of %IF statement 
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Keyword 

TIME 

TO 

TITLE (x) 

TRANSLATE Cs f r [ , p] ) 

TRANSMIT 

TRKOFL 

TRUNC(x) 

U (max-block-size) 

UNALIGNED 

UNBUFFERED 

UNDEFINEDFILE (file-name) 

UNDERFLOW 

UNSPEC(x) 

UPDATE 



Abbreviation 



UNAL 

UNBUF 

UNDF(file-name) 

UFL 



V (max-block-size [ , max- record- size] > 

VARYING VAR 

VBS (max-block-size [ r max- record-size) ) 

VERIFY (expr-1 f expr-2> 

VS (max-block-size [ f max-record-size] ) 



WAIT 

WHILE 

WRITE 



Use of Keyword 

built-in function 

clause of DO statement 

option of OPEN statement 

built-in function 

condition 

option of ENVIRONMENT attribute 

built-in function 

option of ENVIRONMENT attribute 

attribute 

attribute, option of OPEN statement 

condition 

condition 

built-in function, pseudo-variable 

attribute, option of OPEN statement 

option of ENVIRONMENT attribute 

attribute 

option of ENVIRONMENT attribute 

(treated as a V option) 
built-in function 
option of ENVIRONMENT attribute 

(treated as a V option) 

statement 

clause of DO statement 

statement 



ZERODIVIDE 



ZDIV 



condition 



The following keywords can be compiled, but will not execute on TSS/360 for the 
reasons given under "Intended Use of Keyword." 



Keyword 

EVENT 



Abbreviation 



Intended Use of Keyword 

option of CALL statement; (causes abnormal 
termination of execution) 



G (max-mes sage-size) 

GENKEY 

INDEXAREA 

NOLOCK 

NOWRITE 

PENDING 

PRIORITY (x) 

PRIORITY ((task-name)] 

R ( max- record- size) 

REGIONAL 
TASK 

TASK I (task-name) ] 

TRANSIENT 
UNLOCK 



option of ENVIRONMEOT attribute (raises 

UNDEFINEDFILE condition) 
option of ENVIRONMENT attribute (ignored) 
option of ENVIRONMENT attribute (ignored) 
option of READ statement (ignored) 
option of ENVIRONMENT attribute (ignored) 
condition (raises UNDEFINEDFILE condition) 
option of CALL statement (causes abnormal 

termination of execution) 
built-in function, pseudo-variable (causes 

abnormal termination of execution) 
option of ENVIRONMENT attribute (raises 

UNDEFINEDFILE condition) 
option of ENVIRONMENT attribute (raises 

UNDEFINEDFILE condition) 
attribute, option of PROCEDURE statement 

(causes abnormal termination of 
execution) 
option of CALL statement (causes abnormal 

termination of execution) 
attribute (raises UNDEFINEDFILE condition) 
statement (ignored) 
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SECTION 4 ; 



PICTURE SPECIFICATION CHARACTERS 



Picture specification characters appear 
in either the PICTURE attribute or the P 
format item for edit-directed input and 
output. In either case, an individual 
character has the same meaning* A discus- 
sion of the concepts of picture specifica- 
tions appears in Part I, Section 11, "Edit- 
ing and String Handling." 



Picture characters are used to describe 
the attributes of the associated data item, 
whether it is the value of a variable or a 
data item to be transmitted between the 
program and external storage. 

A picture specification always describes 
a character representation that is either a 
character- string data item or a numeric 
character data item, A character- string 
pictured item is one that can consist of 
alphabetic characters, decimal digits, and 
other special characters. A numeric char- 
acter pictured item is one in which the 
data itself can consist only of decimal 
digits, a decimal point and, optionally, a 
plus or minus sign. Other characters gen- 
erally associated with arithmetic data, 
such as currency symbols, can also be spec- 
ified, but they are not a part of the 
arithmetic value of the numeric character 
variable, although the characters are 
stored with the digits and are considered 
to be part of the character-string value of 
the variable. 

Arithmetic data assigned to a numeric 
character variable is converted to charac- 
ter representation. Editing, such as zero 
suppression and the insertion of other 
characters, can be specified for a numeric 
character data item. Editing cannot be 
specified for pictured character-string 
data. 

Data assigned to a variable declared 
with a numeric picture specification (or 
data to be written with a numeric picture 
format item) must be either internal coded 
aritnmetic data or data that can be con- 
verted to coded arithmetic. Thus, assigned 
data can contain only digits and, optional- 
ly, a decimal point and a sign. It should 
not contain any other character, even 
though that character (for example, a cur- 
rency symbol) is specified in the picture 
specification and is to be inserted into 
the data as part of its character-string 
value; if it does, the CONVERSION condition 
is raised- 



Numeric character data to be read using 
the P format item must conform to the spec- 
ification contained in the P format item, 
including editing characters. If the indi- 
cated character does not appear in the 
input stream, the CONVERSION condition is 
raised. 

Data assigned to a variable declared 
with a character-string picture specifica- 
tion Cor data to be written with a 
character-string picture format item) 
should conform, character by character (or 
be convertible, character by character) to 
the picture specification; if it does not, 
the CONVERSION condition is raised. 

Figures in this section illustrate how 
different picture specifications affect the 
representation of values when assigned to a 
pictured variable or when printed using the 
P format item. Each figure shows the orig- 
inal value of the data, the attributes of 
the variable from which it is assigned (or 
written) , the picture specification, and 
the character-string value of the numeric 
character or pictured character- string 
variable. 



PICTURE CHARACTERS FOR CHARACTER- STRING 
DATA 

Only three picture characters can be 

used in character-string picture 
specifications : 

X specifies that the associated position 
can contain any character whose internal 
bit configuration can be recognized by 
the computer in use. 

A specifies that the associated position 
can contain any alphabetic character or 
a blank character. 

9 specifies that the associated position 
can contain any decimal digit or a blank 

character. 

No insertion characters can be specified. 
At least one A or X must appear. 

Figure 23 gives examples of character- 
string picture specifications. In the 
figure, the letter b indicates a blank 
character. Note that assignments are left- 
adjusted, and any necessary padding with 
blanks is on the right. 
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Source 
Attributes 


Source Data | 
Cin constant form) | 

L . X 


Picture | Character-String 
Specification | Value 1 

_ _ x _ . 


T ^ T 

CHARACTER (5) | • 9B/2L' | 


T 

xxxxx 


9B/2L 


CHARACTER C 5) 


•9B/2L' | 


XXX 


9B/ 


CHARACTER (5) 


, 9B/2L' | 


XXXXXXX 


9B/2Lbb 


CHARACTER (5) 


'ABCDE' | 


AAAAA 


ABCDE 


CHARACTER C 5) 


'ABCDE' | 


AAAAAA 


ABCDEb 


CHARACTER (5) 


f ABCDE" | 


AAA 


ABC 


CHARACTER C 5) 


1 12/34' | 


99X99 


12/34 


CHARACTER (5) 


'L26.7' | 


A99X9 


L26.7 



L .. X .X -, 



X - 



| X A variable declared with a character-string picture specification has a character- 
string value only. 

L . 

Figure 23. Pictured Character-String Examples 
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PICTURE CHARACTERS FOR NUMERIC CHARACTER 
DATA 

Numeric character data must represent 
numeric values; therefore r the associated 
picture specification cannot contain the 
characters X or A. The picture characters 
for numeric character data can specify 
detailed editing of the data. 

A numeric character variable can be con- 
sidered to have two different kinds of 
value, depending upon its use. They are 
(1) its arithmetic value and C2) its 
character- string value. 

The arithmetic value is the value ex- 
pressed by the decimal digits of the data 
item, the assumed location of a decimal 
point, and possibly a sign. The arithmetic 
value of a numeric character variable is 
used whenever the variable appears in an 
expression that results in a coded arithme- 
tic value or whenever the variable is 
assigned to a coded arithmetic, numeric 
character, or bit-string variable. In such 
cases, the arithmetic value of the numeric 
character variable is converted to internal 
coded arithmetic representation. 

The character-string value is the value 
expressed by the decimal digits of the data 
item, as well as all of the editing and in- 
sertion characters appearing in the picture 
specification. The character-strirg value 
does not, however, include the assumed 
location of a decimal point, as specified 
by the picture character V. The character- 
string value of a numeric character vari- 
able is used whenever the variable appears 
in a character-string expression operation 
or in an assignment to a character-string 



variable, whenever the data is printed 
using list-directed or data-directed out- 
put, or whenever a reference is made to a 
Character-string variable that is defined 
en the numeric character variable. In such 
cases, no data conversion is necessary. 

The picture characters for numeric char- 
acter specifications may be grouped into 
the following categories: 

• Digit and Decimal- Point Specifiers 

• Zero Suppression Characters 

• Insertion Characters 

• Signs and Currency Symbol 

• Credit, Debit, and Overpunched Signs 

• Exponent Specifiers 

• Scaling Factor 

• Sterling Pictures 

The picture characters in these groups 
may be used in various combinations. Con- 
sequently, a numeric character specifica- 
tion can consist of two or more parts such 
as a sign specification, an integer sub- 
field, a fractional subfield and, for 
floating-point, an exponent field. A 
sterling picture specification contains 
separate fields for pounds, shillings, and 
pence; the pence field can have an integer 
subfield and a fractional subfield. 

A major requirement of the picture spec- 
ification for numeric character data is 
that each field must contain at least one 
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picture character that specifies a digit 
position. This picture character, however, 
need not be the digit character 9. Other 
picture characters, such as the zero 
suppression characters (Z or * or Y) , also 
specify digit positions. At least one of 
these characters must be used to define a 
numeric character specification. 

The maximum length of a picture describ- 
ing a numeric field, after expansion of 
iteration factors, is 255. 



DIGIT AND DECIMAL-POINT SPECIFIERS 

The picture characters 9 and V are used 
in the simplest form of numeric character 
specifications that represent fixed-point 
decimal values. 



(Note that if significant digits are 
truncated on the left, the result is 
undefined and a SIZE interruption will 
occur, if SIZE is enabled.) If no V 
character appears in the picture speci- 
fication of a fixed-point decimal value 
Cor in the first field of a picture 
specification of a floating-point decim- 
al value), a V is assumed at the right 
end of the field specification. This 
can cause the assigned value to be trun- 
cated, if necessary, to an integer. The 
V character cannot appear more than once 
in a picture specification. The V is 
considered to be a subfield delimiter in 
the picture specification; that is, the 
portion preceding the V and the portion 
following it (if any) are each a sub- 
field of the specification. 



Figure 24 gives examples of numeric 
character specifications. 

9 specifies that the associated position 
in the data item is to contain a decimal 
digit. 

V specifies that a decimal point is 

assumed at this position in the asso- 
ciated data item. However, it does not 
specify that an actual decimal point is 
to be inserted. The integer and frac- 
tional parts of the assigned value are 
aligned on the V character; therefore, 
an assigned value may be truncated or 
extended with zero digits at either end. 



ZERO SUPPRESSION CHARACTERS 

The zero suppression picture characters 
specify conditional digit positions in the 
character-string value and may cause lead- 
ing zeros to be replaced by asterisks or 
blanks and nonleading zeros to be replaced 
by blanks. Leading zeros are those that 
occur in the leftmost digit positions of 
fixed-point numbers or in the leftmost 
digit positions of the two parts of 
floating-point numbers, that are to the 
left of the assumed position of a decimal 
point, and that are not preceded by any of 
the digits 1 through 9. The leftmost non- 
zero digit in a number and all digits, 
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T 
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Character-String 
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| FIXED (5) 
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12345 
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99999 




T 


12345 




| FIXED C 5) 










12345 










99999V 






12345 




| FIXED C 5) 










12345 










999V99 






34500 2 




| FIXED C 5) 










12345 










V99999 






OOOOO 2 




| FIXED C 7) 










1234567 










99999 






345672 




| FIXED (3) 










123 










99999 






00123 




| FIXED C 5, 2) 










123.45 










999V99 






12345 




| FIXED (7, 2) 










12345.67 










9V9 






56 2 




1 FIXED (5, 2) 




1. 






123.45 




-X 






99999 




_ X _ 


00123 


j 


| ±The arithmetic value is the value expressed by the digits and the 
| location of the V in the specification. 

| 2 In this case, PL/I does not define the result since significant di 
| truncated on the left. The result shown, however, is that given f 
| implementations. 


actual or assumed 

gits have been 
or System/360 


'~T 



Figure 24. Pictured Numeric Character Examples 
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zeros or not, to the right ot it represent 
significant digits. Note that a floating- 
point number can also have a leading zero 
in the exponent field. 

Figure 25 gives examples of the use of 
zero suppression characters. In the 
figure, the letter b indicates a blank 
character. 

Z specifies a conditional digit position 
and causes a leading zero in the asso- 
ciated data position to be replaced by a 
blank character. When the associated 
data position does not contain a leading 
zero, the digit in the position is not 
replaced by a blank character. The pic- 
ture character Z cannot appear in the 
same subfield as the picture character 
*, nor can it appear to the right of a 
drifting picture character or any of the 
picture characters 9, T, I, or R in a 
field. 

* specifies a conditional digit position 
and is used the way the picture charac- 
ter Z is used, except that leading zeros 



are replaced by asterisks. The picture 
character * cannot appear with the pic- 
ture character Z in the same subfield, 
ncr can it appear to the right of a 
drifting picture character or any of the 
picture characters 9, T, I, or R in a 
field. 

Y specifies a conditional digit position 
and causes a zero digit, leading or non- 
leading, in the associated position to 
be replaced by a blank character. When 
the associated position does not contain 
a zero digit, the digit in the position 
is not replaced by a blank character. 

Note: If one of the picture characters Z 
or * appears to the right of the picture 
character V, then all fractional digit 
positions in the specification, as well as 
all integer digit positions, must employ 
the Z or * picture character, respectively. 
When all digit positions to the right of 
the picture character V contain zero 
suppression picture characters, fractional 
zeros of the value are suppressed cnly if 
all positions in the fractional part con- 



Source 
Attributes 


-L- 


Source Data 
(in constant form) 


-i. 


Picture 
Specification 


Character- String 
Value 1 


FIXED C 5) 


T 


12345 


T 


ZZZ99 


. 

12345 


FIXED (5) 




00100 




ZZZ99 


bblOO 


FIXED (5) 




00000 




ZZZ99 


tbbOO 


FIXED (5) 




00100 




ZZZZZ 


bblOO 


FIXED (5) 




00000 




ZZZZZ 


fcbbbb 


FIX£D(5,2) 




123.45 




ZZZ99 


tb!23 


FIXED(5,2) 




001.23 




ZZZV99 


bbl23 


FIXED (5) 




12345 




ZZZV99 


34500^ 


FIXED C 5) 




00000 




ZZZVZZ 


tbbbb 


FIXED (5) 




00100 




***** 


**100 


FIXED (5) 




00000 




***** 


***** 


FIXEDC5,2> 




000.01 




***v** 


***01 


FIXED (5) 




00100 




YYYYY 


bblbb 


FIXED (5) 




10203 




9Y9Y9 


Ib2b3 



^ a x x 4 

^The arithmetic value is the value expressed by the digits and the actual or assumed 

location of the V in the specification. 
2 In this case, PL/I does not define the result since significant digits have been 

truncated on the left. The result shown, however, is that given for System/360 

implementations . 



Figure 25. Examples of Zero Suppression 
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tain zeros and all integer positions have 
been suppressed. The entire character- 
string value of the data item will then 
consist of blanks or asterisks. No digits 
in the fractional part are replaced by 
blanks or asterisks if the fractional part 
contains any significant digit. 



INSERTION CHARACTERS 

The picture characters comma (,), point 
(.), slash (/), and blank (B) are insertion 
characters? they cause the specified char- 
acter to be inserted into the associated 
position of the numeric character data. 
They do not indicate digit positions, but 
are inserted between digits. Each does, 
however, actually represent a character 



position in the character-string value, 
whether or not the character is suppressed. 
The comma, point, and slash are conditional 
insertion characters; within a string of 
zero suppression characters, they, tco, may 
be suppressed. The blank (B) is an uncon- 
ditional insertion character; it always 
specifies that a blank is to appear in the 
associated position. 



Note : Insertion characters are applicable 
cnly to the character- string value. They 
specify nothing about the arithmetic value 
of the data item. 

Figure 26 gives examples of the use of 
insertion characters. In the figure, the 
letter b indicates a blank character. 



Source 
Attributes 



Source Data 
(in constant form) 



Picture 
Specification 



Character- St ring 
Value 1 



FIXEDC4) 

FIXED(6,2) 
FIXED (4, 2) 
FIXEDC4, 2) 
FIXED (4, 2) 
FIXED C 4, 2) 
FIX£D(4,2) 
FIXED(9,2) 
FIXED (7,2) 
FIXED (7, 2) 
FIXED (9,2) 
FIXED (6) 
FIXED (6) 
FIXED (6) 
FIXEDC6) 
FIXED (6) 
FIXED C6) 
FIXEDC6) 
FIXED (3) 
FIXED(2) 



1234 

1234.56 

12.34 

00.03 

00.03 

12.34 

00.00 

1234567.89 

12345.67 

00123.45 

1234567.89 

123456 

123456 

001234 

000012 

000000 

000000 

123456 

123 

12 



9,999 

9, 999V. 99 

ZZ.VZZ 

ZZ.VZZ 

ZZV.ZZ 

ZZV.ZZ 

ZZV.ZZ 

9,999,999.V99 

**,999V„99 

**, 999V. 99 

9. 999. 999V, 99 

99/99/99 

99.9/99.9 

ZZ/ZZ/ZZ 

ZZ/ZZ/ZZ 

ZZ/ZZ/ZZ 
#*/**/** 

99B99B99 

9BB9BB9 

9BB/9BB 

by the digits and 



1,234 

1,234.56 

12.34 

bbb03 

bb.03 

12..34 

bbbbb 

1,234,567.89 

12 f 345.67 

***123.45 

1.234.567,89 

12/34/56 

12.3/45.6 

bbb!2/34 

bbbbbb!2 

bbbbbbbb 

******** 

12b34bS6 

Ibb2bb3 

lbb/2bb 



^-The arithmetic value is the value expressed 
location of the V in the specification. 



the actual or assumed 



Figure 26. Examples of Insertion Characters 
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Comma C a } s causes a comma to be inserted 
into the associated position of the numeric 
character data when no zero suppression 
occurs. If zero suppression does occur, 
the comma is inserted only when an unsup- 
pressed digit appears to the left of the 
comma position, or when a ¥ appears immedi- 
ately to the left of it and the fractional 
part contains any significant digits. In 
all other cases where zero suppression 
occurs, one of three possible characters 
isinserted in place of the comma. The 
choice of character to replace the comma 
depends upon the first picture character 
that both precedes the comma position and 
specifies a digit position! 

• If this character position is an 
asterisk, the comma position is 
assigned an asterisk. 

• If this character position is a drift- 
ing sign or a drifting currency symbol 
(discussed later), the drifting string 
is assumed to include the comma posi- 
tion, which is assigned the drifting 
character. 

• If this character position is not an 

asterisk or a drifting character, the 
comma position is assigned a blank 
character * 

In the special case of a conditional in- 
sertion character that is preceded either 
by nothing or only by characters that do 
not specify digit positions, the condition- 
al position will always contain the condi- 
tional insertion character. 

Point (.) : is used the same way the comma 
picture character is used, e*cept that a 
point (.) is assigned to the associated 
position. This character nearer causes 
point alignment in the picture specifica- 
tions of a fixed-point decimal number and 
is not a part of the arithmetic value of 
the data item. That function is served 
solely by the picture character V. Unless 
the ¥ actually appears, it is assumed to be 
to the right of the rightmost digit posi- 
tion in the field, and point alignment is 
handled accordingly, even if the point in- 
sertion character appears elsewhere* The 
point Cor the comma or slash) can be used 
in conjunction with the ¥ to cause inser- 
tion of the point (or comma or slash) in 
the position that delimits the end of the 
integer portion and the beginning of the 
fractional portion of a fixed-point (or 
floating-point) number, as might fca desired 
in printing, since the ¥ does not cause 
printing of a point. The point mart imme- 
diately precede or Immediately follow the 
¥. If the point precedes the *\ it will be 
inserted only if a significant digit 
appears to the left of the ¥, even if all 
fractional digits are significant. If the 



point immediately follows the ¥, it will be 
suppressed if all digits to the right of 
the ¥ are suppressed, but it will appear if 
there are any fractional digits (along with 

any intervening zeros) . 

Slash (/) : is used the same way the comma 
picture character is used,, eiccept that a 
slash (/) is inserted in the associated 
position* 

Blank (B) : specifies that a blanfcvcharac- 

ter always be inserted into the associated 
position of the character-string value of 
the numeric character data* 



SIGNS AND CURRENCY SYMBOL 

The picture characters S # ♦ , and - spec- 
ify signs in numeric character data. The 
picture character $ specifies a currency 
symbol in the character- string value of nu- 
meric character data. 

These picture characters may be used in 
either a static or a drifting manner. A 
drifting character is similar to a zero 
suppression character In that it can cause 
zero suppression. However, the character 
specified by the drifting string is always 
inserted in the position specified by the 
end of the drifting string or in the posi- 
tion immediately to the left of the first 
significant digit. 

The static use of these characters spec- 
ifies that a sign, a currency symbol, or a 
blank always appears in the associated 
position. The drifting use specifies that 
leading zeros are to be suppressed*' In 
this case, the rightmost suppressed posi- 
tion associated with the picture character 
will contain a sign # a blank, or a currency 
symbol. 

A drifting character is epecified by 
multiple use of that character in a picture 
field. Thu8 f if a field contains one cur- 
rency symbol C$) , it is interpreted as 
static? if it contains more than one, it is 
interpreted as drifting. The drifting 
character must be specified in each digit 
position through which it may drift. 

Drifting characters wist appear in 
strings, A string is a sequence of the 
same drifting character, optionally con- 
taining a ¥ and one of the Insertion chara- 
cters comma, point, slash, or B. Any of 
the insertion characters slash, comma, 
point, or B following the Mat drifting 
symbol of the string is considered part of 
the drifting string. However, a following 
¥ terminate!! the drifting string and is not 
part of it, A field of a picture specifi- 
cation can contain only one drifting 
string* A drifting string cannot be pre- 
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ceded by a digit position. The picture 
characters * and Z cannot appear to the 
right of a drifting string in a field. 

Figure 27 gives examples of the use of 

drifting picture characters. In the 
figure , the letter b indicates a blank 
character. 

The position in the data associated with 
the characters slash, comma, point f and B 
appearing in a string of drifting charac- 
ters will contain one of the following: 

• slash, comma, point, or blank if a sig- 
nificant digit has appeared to the left 

• the drifting symbol, if the next posi- 
tion to the right contains the leftmost 
significant digit of the field 

» blank, if the leftmost significant digit 
of the field is more than one position 
to the right 



If a drifting string contains the drift- 
ing character n times, then the string is 
associated with n-1 conditional digit posi- 
tions. The position associated with the 
leftmost drifting character can contain 
only the drifting character or blank, never 
a digit. If a drifting string is specified 
for a field, the other potentially drifting 
characters can appear only once in the 
field, i.e., the other character represents 
a static sign or currency symbol. 

If a drifting string contains a V within 
it, the V delimits the preceding portion as 
a subfield, and all digit positions of the 
subfield following the V must also be part 
of the drifting string that commences the 
second subfield. 

Only one type of sign character can 
appear in each field. An S, ♦ , or - used 
as a static character can appear to the 
left of all digits in the mantissa and 
exponent fields of a floating-point speci- 



j Source 
| Attributes 

L , __. 


1 c 

j. 


Source Data 
in constant form) 


»x 


Picture 
Specification 


x_ 


Character-String 

Value 1 


| FIXED(5 f 2> 


T 


123.45 




T 


$999V.99 


— t 


$123.45 


| FIXEDC5,2) 




001.23 






$ZZZV.99 




$bbl.23 


| FIXED(5,2) 




000.00 






$ZZZV.ZZ 




bbbbbbb 


1 FIXED (1) 











$$$.$$ 




bbbbbb 


| FIXED(5,2) 




123.45 






$$$9V.99 




$123.45 


| FIXED(5,2) 




001.23 






$$$9V.99 




bb$1.23 


| FIXEDC5,2) 




012.00 






99$ 




12$ 


| FIXED C 2) 




12 






$$$,999 




bbb$012 


| FIXED C 4) 




1234 






$$$,999 




b$l,234 


I FIXED(5,2) 




123.45 






S999V.99 




♦123.45 


| FIXED C 5, 2) 




-123.45 






S999V.99 




-123.45 


| FIXEDC5,2) 




-123.45 






♦999V. 99 




bl23.45 


| FIXED (5, 2) 




123.45 






-999V. 99 




bl23.45 


| FIXEDC5,2) 




123.45 






999V. 99S 




123. 45* 


I FIXED(5,2> 




001.23 






++B+9V.99 




bbb*1.23 


I FIXEDC5,2) 




001.23 






9V.99 




bbbl.23 


| FIXED(5,2) 
|_„„ 

| *The arithmetic 
| location of the 


A - 

value 
V in 


-001.23 | 

x 

is the value expressed 
the specification. 


SSS9V. 99 
by the digits and 


— .li- 
the 


bb-1.23 

actual or assumed 



-H 



Figure 27. Examples of Drifting Picture Characters 
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fication, and either to the right or left 
of all digit positions of a fixed-point 
specification . 



In the 
after the 
suppress!© 
if all of 
are zero, 
will then 
signif ican 
fractional 
unsuppress 

$ specifi 
charact 
a drift 
static 
specifi 
placed 
static 
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of all 
tion . 
ing use 



case in which ail digit positions 
V contain drifting characters, 
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The resulting edited data item 
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portion will appear 
ed. 



es the currency 
er appears more 
ing character; 
character. The 
es that the cha 
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character roust 
t of all digit 
f a specificati 
digit positions 
See details abo 
of the charact 
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static char 
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on or to the 

in a specif 
ve for the d 
er . 
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it is 

is a 
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be 
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r to 

a 

right 
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rif t- 



specifies the plus sign character ( + ) if 
the data value is >0, otherwise it spec- 
ifies the minus sign character (-■) . The 
character may be drifting or static. 
The rules are identical to those for the 
currency symbol. 

specifies the plus sign character (+) if 
the data value is >Q, otherwise it spec- 
ifies a blank. The character may be 
drifting or static. The rules are 
identical to those for the currency 
symbol. 

specifies the minus sign character (-) 
if the data value is <0, otherwise it 
specifies a blank. The character may be 



drifting or static. The rules are 
identical to those for the currency 
symbol. 



CREDIT, DEBIT, AND OVERPUNCHED SIGNS 

The character pairs CR (credit) and DB 
(debit) specify the signs of real numeric 
character data items and usually appear in 
business report forms. 

Any of the picture characters T, I, or R 
specifies an overpunched sign in the asso- 
ciated digit position of numeric character 
data. An overpunched sign is a 12-punch 
(for plus) or an 11 -punch (for minus) 
punched into the same column as a digit. 
It indicates the sign of the arithmetic 
data item* Only one overpunched sign can 
appear in a specification for a fixed-point 
number. A floating-point specification can 
contain two, one in the mantissa field and 
cne in the exponent field. The overpunch 
character can, however, be specified for 
any digit position within a field. The 
overpunched number then will appear in the 
specified digit position. 

From the user's terminal keyboard, an 
"overpunch" is not possible. The user 
should be careful to avoid Y, D r or R in 
any picture that will be be read from his 
terminal. 

Note : When an overpunch character occurs 
in a P format item for edit-directed input, 
the corresponding character in the input 
stream may contain an overpunched sign. 

Figure 28 gives examples of the CR, DB, 
and overpunch characters. In the figure, 
the letter b indicates a blank character. 



T — . „. „ 1 

Character-String 
Value 1 



Source 
Attributes 



Source Data 
(in constant form) 



Picture 

Specification 



4 



H 



h 



FIXED(3) 
FIXED(4, 2) 
FIXED(4,2) 
FIXED (4, 2) 
FIXED (4) 
FIXED (4) 
FIXED(4) 



-123 

12.34 

-12.34 

12.34 

1021 

-1021 

1021 



$Z.99CR 
$ZZV, 99CR 
$ZZV.99DB 

$ZZV.99DB 
9991 
Z99R 
99T9 



$1. 23CR 
$12 % 34bk 

$12.34DB 
$12.34bb 

102A 
102J 
10B1 



^The arithmetic value is the value expressed by the digits and the actual or assumed 
location of the V in the specification. 

L . . . — .-_ — , . „. 

Figure 28. Examples of CR, DB, T, I, and R Picture Characters 
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Source 
Attributes 


i Source Data 

: (in constant form) 


Picture | Character-String 
[ Specification | Value 1 

L - X ■ - ■ - _____ 


FLOAT IS) | .12345E06 


V.99999E99 


•12345E06 


FLOAT C 5) 


.12345E-06 


V.99999ES99 


.123H5E-06 


FLOAT (5) 


.12345E+06 


V.99999KS99 


.12345+06 


FLOAT (5) 


-123.4SE+12 


S999V.99ES99 


-123.45E+12 


FLOAT (5) 


001.23E-01 


SSS9. V99ESS9 


+123.00Eb-3 


FLOAT (5) 


001.23E+04 


ZZZV.99KS99 


123.00+02 


FLOAT (5) 


001.23E+04 


SZ99V.99ES99 


+123.Q0E+02 


FLOAT ( 5 ) 


001.23E+04 j 


SSSSV.99E-99 


+123.00Eb02 



X . 



-X X- 



. . ., 



| A The arithmetic value is the value expressed by the mantissa, multiplied by 10 to the 
power indicated in the exponent field. 



-« — . . „j 



Figure 29. Examples of Floating-Point Picture Specifications 



CR specifies that the associated positions 
will contain the letters CR if the 
value of the data is less than zero. 
Otherwise, the positions will contain 
two blanks. The characters CR can 
appear only to the right of all digit 
positions of a field. 



DB is used the same way that CR is used 
except that the letters DB appear in 
the associated positions. 



T specifies that the associated position, 
on input, will contain a digit over- 
punched with the sign of the data. It 
also specifies that an overpunch is to 
be indicated in the character-string 
value. 

I specifies that the associated position, 
on input, will contain a digit over- 
punched with + if the value is >0; 
otherwise, it will contain the digit 
with no overpunching. It also speci- 
fies that an overpunch is to be indi- 
cated in the character-string value if 
the data value is >0. 

R specifies that the associated position, 
on input, will contain a digit over- 
punched with - if the value is <0 ; 
otherwise, it will contain the digit 
with no overpunching. It also speci- 
fies that an overpunch is to be indi- 
cated in the character-string value if 
the data value is <0 . 

Note ; The picture characters CR, DB, T, I, 
and R cannot be used with any other sign 
characters in the same field. 



EXPONENT SPECIFIERS 

The picture characters K and E delimit 
the exponent field of a numeric character 
specification that describes floating-point 
decimal numbers. The exponent field is 
always the last field of a numeric charac- 
ter floating-point picture specification. 
The picture characters K and E cannot 
appear in the same specification. 

Figure 29 gives examples of the use of 
exponent delimiters. In the figure, the 
letter b indicates a blank character. 

K specifies that the exponent field 

appears to the right of the associated 
position. It does not specify a charac- 
ter in the numeric character data item. 

E specifies that the associated position 
contains the letter E, which indicates 
the start of the exponent field. 

The value of the exponent is adjusted in 
the character- string value so that the 
first signiiicant digit of the first field 
(the mantissa) appears in the position 
associated with the first digit specifier 
of the specification (even if it is a zero 
suppression character) . 



SCALING FACTOR 

The picture character F specifies a 
scaling factor for fixed-point decimal num- 
bers. It appears at the right end of the 
picture specification and is used in the 
following format: 

F ([+)-] decimal- integer- constant) 
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Source 
Attributes 


T — - _ _ „__ T — , 

| Source Data | 
| (in constant form) | 
i. _ _ x_ - 


Picture 
Specification 


T — 

4- - 


Character- String 
Value* 


— 1 
i 


FIXED (14,0) 


T T 

| 1200 | 


99F(2) 


T 


12 


! 


FIXEDC7, 0) 


| -1234500 | 


S999V99F(4) 




-12345 




FIXEDC5, 5) 


f .00012 I 


99F(-5) 




12 




FIXED(6,6> 


| .012345 | 


999V99F(~4) 




12345 





h 



- X 



._. . . X 



X . J 



^The arithmetic value is the same as the character-string value, multiplied by 10 to 
the power of the scaling factor. 



i . 



Figure 30. Examples of Scaling Factor Picture Characters 



. . . — T ~ T . 

Source | Source Data j 
Attributes | (in constant form) | 



Picture 
Specification 



j 



. T — . . . — . 1 

| Character-String 
I Value 3 - 



L„ . + . ^X ._„ — .„„_- + . _ ^ 



l" 



FIXEDC4) | 

I 
FIXEDC4) I 

X- 



0534 
0019 



| GKZ9M.8M.99V.9CR 

I 

I GMZZM.ZZ^.ZZP 



. . X 



b2.4.06.0bb 
bb.bl.07D 



„.„x _„ . . H 



I^The arithmetic value of a numeric character variable declared with a sterling picture 
specification is its value expressed as a valid sterling fixed-point constant, which 
for arithmetic operations is always converted to its value expressed in pence. 



, . — . — . — ._ j 



Figure 31. Examples of Sterling Picture Specifications 



F specifies that the optionally signed 
decimal integer constant enclosed in 
parentheses is the scaling factor. The 
scaling factor specifies that the 
decimal point in the arithmetic value 
of the variable is that number of 
places to the right (if the scaling 
factor is positive) or to the left (if 
negative) of its assumed position in 
the character-string value. 

For System/360 implementations, the 
scaling factor cannot specify a fixed- 
point number that contains more than 15 
digits. 

Figure 30 shows examples of the use of 
the scaling factor picture character. 



STERLING PICTURES 

The following picture characters are 
used in picture specifications for sterling 
data: 

8 specifies the position of a shilling 

digit in BSI single-character represen- 
tation. Ten shillings is represented 
by a 12- punch (S) and eleven through 
nineteen shillings are represented by 
the characters A through I, 
respectively. 



specifies the position of a pence digit 
in BSI single- character representation. 
Ten pence is represented by a 12-punch 
(£) and eleven pence is represented by 
an ll~punch (-) . 



6 specifies the position of a pence digit 
in IBM single-character representation. 
Ten pence is represented by an 11-punch 
(-) and eleven pence is represented by 
a 12-punch U) . 

P specifies that the associated position 
contains the pence character D. 

G specifies the start of a sterling pic- 
ture. It does not specify a character 
in the numeric character data item. 

p specifies that the associated position 
contains the shilling character S. 

K specifies the start of a field. It 

does not specify a character in the nu- 
meric character data item. 

Figure 31 gives examples of the use of 
sterling picture specifications. 

Sterling data items are considered to be 
real fixed-point decimal data. When 
involved in arithmetic operations, they are 
converted to a value representing fixed- 
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point pence. Sterling pictures have the 
general form: 



PICTURE 

f G [editing~character-13 . .. 

M pounds-field 

M Cseparator-1) . .. 

shillings- field 

M [separator-2] . .. 
pence-field 

[editing-character~2) ..-• 

"Editing character 1" can be one or more 
of the following static picture characters: 



The "pounds field" can contain the fol- 
lowing picture characters : 

ZY*9TIR,$+-S 

The last four characters ($ ♦ - S) must 
be drifting characters. The comma can be 
used as an insertion character. 

"Separator 1" can be one or more of the 
following picture characters: 

/ . B 

The "shillings field" can be: 

{99 | ¥Y | ZZ 1 Y9 | Z9 | YZ | 8> 



One of the nines can be replaced by T ( I, 
cr R f if no other sign indicator appears in 
any of the fields of the specification. 

"Separator 2" can be one or more of the 

picture characters: 

/ . B H 
The "pence field" takes the form: 
C99|YY|ZZ |Y9|7|Z9 | YZ | 6 } 
[[V|V.|.V] 9|Z|Y3... 



One cf the nines can be replaced by T, I, 
or R, if no other sign indicator appears in 
any of the fields of the specification. 

"Editing character 2" can be one or more 
of the static picture characters $, +, - f 
or S and one or more of B, P, CR # cr DB. A 
sign character or CR or DB can appear only 
if no other sign indicator appears in any 
of the fields of the specification. 

The pounds, shillings, and pence fields 
must each contain at least one digit 
position. 

Zero suppression in sterling pictures is 
performed on the total data item, not 
separately on each of the pounds, shil- 
lings, and pence fields. The Z picture 
character is not allowed to the right of a 
6, 7, 8, or 9 picture character in a ster- 
ling specification. In sterling pictures, 
the field separator characters slash (/> , 
point (.), B, and H are never suppressed. 
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SECTION 5: EPIT-PIRSCTED FORMAT ITEMS 



This section describes each of the edit- 
direct ed forirat items that can appear in 
the format list of a GET or PUT statement. 

There are three categories of format 
items: data format items, control format 
items, and the remote format item. 

In this section, the three categories 

are discussed separately and the format 
items are listed under each category. The 
remainder of the section contains detailed 
discussions of each of the format items, 
with the discussions appearing in alphabe- 
tic order. 



:r, I A FORMAT I TENS 

A data format item describes the exter- 
nal format of a single data item. 

For input, tne data in the stream is 
considered to be a continuous string of 
characters; all blanks are treated as 
characters in the stream, as are quotation 
marks. Each data format item in a GET 
statement specifies the number of charac- 
ters to be obtained from the stream and 
describes the way these characters are to 
be interpreted. Strings should not be en- 
closed in quotation marks, nor should the 
letter 3 be used to identify tit strings. 
If the characters in tne stream cannot be 
interpreted in the manner specified, the 
CONVERSION condition is raised. 

For output, the data in the stream takes 
the form specified by the format list. 
Each data format item in a PUT statement 
specifies the width of a field into which 
the associated data item, in character form 
is to be placed and describes the format 
that the value is to take. Enclosing apos- 
trophes are not inserted, nor is the letter 
E to identify bit strings. 
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specification is on the left for arithmetic 
items, on the right for string items. 

Note that the value of binary data both 
on input and output is always represented 
in decimal form for edit-directed 
transmission. 

Following is a list of data format 

items: 



Fixed-point 
format item 

Floating-point 
format item 

Complex format 

item 

Picture format 
item 

Bit-string 
format item 

Character- string 
format item 



F (specification) 

E (specification) 

C (specification) 

P 'picture- specification 1 

B (specification) 

A (specification) 



CONTROL FORMAT ITEMS 

The control format items specify the 

layout of the data set associated with a 

file. The following is a list of centre! 

format items ; 



Paging format 
item 

line skipping 

format item 

Line position 

format item 

Column position 

Spacing 

format item 



PAGE 

SKIP[ (specification) ] 

LINE (specification) 

COLUMN (specification) 
X (specification) 



A control format item has no effect 
unless it is encountered before the data 
list is exhausted. 

The PAGE and LINE format items apply 
only to output and only to files with the 
PRINT attribute. The SKIP and COLUMN for- 
mat items apply to both input and output. 

The PAGE, SKIP, and LINE format items 
have the same effect as the corresponding 
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options of the PUT statement (and of the 
GET statement, in the case of SKIP), except 
that the format items take effect only when 
they are encountered in the format list, 
while the options take effect tefore any 
data is transmitted. 

The COLUMN format item positions the 
file to the specified character position in 
the current line. 

The spacing format item specifies rela- 
tive horizontal spacing. On input, it 
specifies a number of characters in the 
stream to be skipped over and ignored; on 
output, it specifies a number of blanks to 
be inserted into the stream. 



REMOTE FORMAT ITEM 

The remote format item specifies the 
label of a FORMAT statement that contains a 
format list wnich is to be taken to replace 
the remote format item. 

The remote format item is: 

R (statement-label-designator) 

The "statement label designator" is a 
label constant or an element label 
variable. 



USE OF FORMAT ITEMS 



used. It specifies the number cf 
character positions in the data stream 
that contain (or will contain) the 
string • 

2. On input, the specified number of 
characters is obtained from the data 
stream and assigned, with any neces- 
sary conversion, truncation, or pad- 
ding, to the associated element in the 
data list. The field width is always 
required en input, and if it has a 
value less than or equal to zero, a 
null string is assumed. If apostro- 
phes appear in the stream, they are 
treated as characters in the string. 

3. On output, the associated element in 
the data list is converted, if neces- 
sary, to a string of characters and is 
truncated or extended with blanks on 
the right to the specified field width 
before being placed into the data 
stream. If the field width is less 
than or equal to zero, the format item 
and its associated element in the data 
list are skipped, and no characters 
are placed into the data stream. En- 
closing apostrophes are never 
inserted. If the field width is not 
specified, it is assumed to be equal 
to the character-string length of the 
element named in the data list (after 
conversion, if necessary, according to 
the rules given in Part II , Section 6, 
"Problem Data Conversion")* 



The "specification" that is listed above 
for all but the picture, PAGE, and remote 
format items can contain one or more ex- 
pressions. Such expressions can be speci- 
fied as decimal integer constants, as ele- 
ment variables, or as other element expres- 
sions. The value assigned to a variable 
during an input operation can be used in an 
expression in a format item that is asso- 
ciated with a later data item. An expres- 
sion is evaluated and converted to an 
integer each time the format item is used. 



ALPHABETIC LIST OF FORMAT ITEMS 

The A Format Item 

The A format item is: 

A ((field-width)) 

The character-string format item 
describes the external representation of a 
string of characters. 

General rules: 

1. The "field width" is an expression 

that is evaluated and converted to an 
integer each time the format item is 



The B Format Item 

The B format item is: 

B [(field-width)] 

The bit-string format item describes the 
external representation of a bit string. 
Each bit is represented by the character 
or 1. 

General rules: 

1. The "field width" is an expression 
that is evaluated and converted to an 
integer each time the format item is 
used. It specifies the number of 
data-stream character positions that 
contain (or will contain) the bit 
string. 

2. On input, the character representation 
of the bit string may occur anywhere 
within the specified field. Blanks, 
which may appear before and after the 
bit string in the field, are ignored. 
Any necessary conversion occurs when 
the bit string is assigned to the 
associated element in the data list. 
The field width is always required on 
input, and if it is less than or equal 
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to zero, a null string is assumed. 
Any character other than or 1 in the 
string, including embedded blanks, 
quotation marks, or the letter B, will 
raise the CONVERSION condition. 

3. On output, the character representa- 
tion of the bit string is left- 
adjusted in the specified field, and 
necessary truncation or extension with 
blanks occurs on the right- Any 
necessary conversion to bit-string is 
performed*, No apostrophes are 
inserted, nor is the identifying let- 
ter B. The field width need not be 
specified when the associated element 
in the data list is a bit string; in 
this case, the current length of the 
associated string is used, and the 
data item completely fills the field. 
The field width is always required if 
the data-list item is arithmetic or 
pictured. If the field width is less 
than or equal to zero, the format item 
and its associated element in the data 
list are skipped, and no characters 
are, placed into the data stream. 

he C Format Item 

The C format item is: 

C Creal-f ormat-item[ ,reai-f ormat-itero] > 

The complex format item describes the 
xternal representation of a complex data 
tem. 

eneral rules: 

1. Each "real format item 1 * is specified 
by one of the F, E, or P format items. 
The P format item must describe fixed- 
point or floating-point numeric 
character data; it cannot describe 
sterling or character-string data. 

2. On input, the complex format item 
describes the real and imaginary parts 
of the complex data item within adja- 
cent fields in the data stream. If 
the second real format item is 
omitted, it is assumed to be the same 
as the first. The letter I will cause 
the CONVERSION condition to be raised. 

3. On output, the real format items 
describe the forms of the real and 
imaginary parts of the complex data 
item in the data stream. If the 
second real format item is omitted, it 
is assumed to be the same as the 
first. The letter I is never appended 
to the imaginary part. If the second 
real format item (or the first, if 
only one appears) is an F o^ E item, 
the internal sign will be printed only 
if the value of the imaginary part is 



less than zero. If the real format 
iteir is a P item, the sign will be 
printed only if the S or - or + pic- 
ture character is specified. If the J 
is to be appended, it must be speci- 
fied as a separate data item in the 
data list, immediately following the 
variable that specifies the complex 
item. The I, then, roust have a corre- 
sponding format item (either A or P) . 



The COLUMN Format Item 

The COLUMN format item is: 

COLUMN ( charact er- position ) 

The column position format item posi- 
tions the file to a specified character 
position within the line. It can be used 
with either input or output files. 

General rules: 

1. The "character position" can be speci- 
fied by an expression, which is evalu- 
ated and converted to an integer each 
time the format item is used. 

2. The file is positioned to the speci- 
fied character positon in the current 
line. On input, intervening character 
positions are ignored; on output, they 
are filled with blanks. If the file 
is already positioned after the speci- 
fied character positon, the current 
line is completed and a new line is 
started; the format item is then ap- 
plied to the new line. 

3. If the specified character position 
lies beyond the rightmost character 
position of the current line, cr if 
the value of the expression for the 
character position is less than one, 
then the character position is assumed 
to be one. 

Note : The rightmost character position 
is determined as follows: 

a. For output files, it is determined 
by the line size; 

b. For input files, the compiler uses 
the length of the current logical 
record to determine the line size 
and, hence, the rightmost charac- 
ter position. In the case of V- 
forroat records, this line size is 
equal to the logical record length 
minus the number of bytes contain- 
ing control information. 

4. The COLUMN format item has no effect 
unless it is encountered before the 
data list is exhausted. 
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The E Format Item 



The E format item is: 



E(f ield- width, number~of- fractional-dig its 
[ , nuniber-of-signif icant- digits! ) 



The value expressed by "field 

width" includes trailing blanks, 
the exponent position, the posi- 
tions for the optional plus or 

minus signs # the position for the 
optional letter E, and the posi- 
tion for the optional deciiral 
point in the mantissa. 



The floating-point format item describes 
the external representation of decimal 
arithmetic data in floating-point format. 



General rules: 

1. The "field width," "number of frac- 
tional digits, n and "number of signi- 
ficant digits" can be represented by 
expressions, which are evaluated and 
converted to integers when the format 
item is used. 

"Field width" specifies the total 
number of characters in the field. 

"Number of fractional digits" speci- 
fies the number of digits in the man- 
tissa that follow the decimal point; 

"Number of significant digits" speci- 
fies the number of digits that must 
appear in the mantissa. 

2. On input, the data item in the data 
stream is the character representation 
of an optionally signed decimal 
floating-point or fixed-point constant 
located anywhere within the specified 
field. If the data item is a fixed- 
point number, an exponent of zero is 
assumed. 

The external form of a floating-point 
number is: 

[ + |-3 mantissa (EH+|-} exponent 
E [+|-3 

The mantissa roust be a decimal fixed- 
point constant. 

a. The number can appear anywhere 

within, the specified field; blanks 
may appear before and after the 
number in the field and are 
ignored. If the entire field is 
blank, the CONVERSION condition is 
raised. When no decimal point 
appears, the expression for the 
number of fractional digits speci- 
fies the number of character posi- 
tions in the mantissa to the right 
of the assumed decimal point. if 
a decimal point does appear in the 
number, it overrides the s t ecif i- 
cation of the number of the frac- 
tional digits. 



b. The exponent is a decimal integer 
constant. Whenever the exponent 
and preceding sign or letter E are 
omitted, a zero exponent is 
assumed. 

On output, the internal data is con- 
verted to floating-point, and the ex- 
ternal data item in the specified 
field has the following general form: 

[-) {s-d digits}. Cd digits} 
E {+(-} exponent 

In this form, s represents the number 
of significant digits, and d repre- 
sents the number of fractional digits. 
The value is rounded if necessary. 



b. 
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If the above form of the number 
does not fill the specified field 
on output, the number is right- 
adjusted and extended on the left 
with blanks. If the number of 
significant digits is not speci- 
fied, it is taken to be 1 plus the 
number of fractional digits. For 
Systero/360 implementations , the 
field width for non-negative 
values of the data item must be 
greater than or equal to 5 plus 
the number of significant digits. 
For negative values of the data 
item, the field width must be 
greater than or equal to 6 plus 
the number of significant digits. 
However, if the number of frac- 
tional digits is zero, the decimal 
point is not written, and the 
above figures for the field width 
are reduced by 1. 

The rounding of internal data is 
as follows: if truncation causes 
a digit to be lost from the right, 
and this digit is greater than or 
equal to 5 # then 1 is added to 
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the digit to the left of the trun- 
cated digit. 

d. If the field width is such that 

significant digits or the sign is 
lost, the SIZE condition is 
raised. 

When using the E format item E(w,d,s), 
s must be less than 17 digits. When 
using E(w,d), d must be less tnan 16 
digits. If the number of significant 
digits in E format data is greater 
than 16, then: 



E format input: 
raised 

E format output; 
raised 

The F Format Item 



The F format item is: 



CONVERSION condition 



ERROR condition 



F (fie Id- width [, number-of - fractional- dig its 

t , sea ling-f actor} ] ) 

The fixed-point format item describes 
the external representation of a decimal 
arithmetic data item in fixed-point format. 

General rules: 

1. The "field width," "number of frac- 
tional digits," and "scaling factor" 
can be represented by element expres- 
sions, which are evaluated and con- 
verted to integers when the format 
item is used. 

2. On input, the data item in the data 
stream is the character representation 
of an optionally signed decimal fixed- 
point constant located anywhere within 
the specified field. Elanks may 
appear before and after the number in 
the field and are ignored. If the 
entire field is blank, it is inter- 
preted as zero. 

The number of fractional digits, if 
not specified, is assumed to be zero. 
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If a scaling factor is specified, it 
effectively multiplies the value of 
the data item in the data stream by 10 
raised to the integral value (p>) of 



3. On output, the internal data is con- 
verted, If necessary, to fixed-point; 
the external data is the character 
representation of a decimal fixed- 
point number, rounded if necessary, 
and right-adjusted in the specified 
field. 

If only the field width is specified 
in the format item, only the integer 
portion of the number is written; no 
decimal point appears. 

If both the field width and number cf 
fractional digits are specified, but 
the scale factor is net, both the 
integer and fractional portions of the 
number are written. If the value (d) 
of the number of fractional digits is 
greater than zero, a decimal point is 
inserted before the rightmost d 
digits. Trailing zeros are supplied 
when the number of fractional digits 
is less than d Cthe value d must be 
less than the field width). Suppres- 
sion of leading zeros is applied to 
all digit positions (except the first) 
to the left of the decimal point. 

The rounding of internal data is as 
follows: if truncation causes a digit 
to te lost from the right, and this 
digit is greater than or equal to 5, 

then 1 is added to the digit to the 
left of the truncated digit. 

The integer value (js) of the scaling 
factor effectively multiplies the 
value of the associated element in the 
data list by 10 raised to the power cf 
£, before it is edited into its exter- 
nal character representation. When 
the number of fractional digits is 
zero, only the integer portion of the 
number is used. 

On output, if the value of the fixed- 
point number is less than zero, a 
minus sign is prefixed to the external 
character representation; if it is 
greater than or equal to zero, no sign 
appears. Therefore, for negative 
values of the fixed- point number, the 
field width specification must include 
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a count of both the sign and the deci- 
mal point. 

If the field width is such that signi- 
ficant digits or the sign is lost, the 
SIZE condition is raised. 

The LINE Format Item 

The LINE format item is: 

LINE (line-number) 

The line position format item specifies 
the particular line on a page of a PRINT 
file upon which the next data item is to be 
printed. 

General rules: 

1. The "line number** can be represented 
by an expression, which is evaluated 
and converted to an integer each time 
the format item is used. 

2. The LINE format item specifies that 
blank lines are to be inserted so that 
the next line will be the specified 
line of the current page. 

3. If the specified line has already been 
passed on the current page, or if the 
specified line is beyond the limits 
set by the PAGESIZE option of the OPEN 
statement (or by default), the ENDPAGE 
condition is raised. 

4. If "line number" is less than or equal 
to zero, it is assumed to be one. 

5. The LINE format item has no effect 
unless it is encountered before the 
data list is exhausted. 

If the PAGE occurs in conversational 
mode only three spaces will be taken if the 
file is SYSOUT. 

The P Format Item 

The P format item is: 

P 8 picture-specif ication* 

The picture format item describes the 
external representation of numeric charac- 
ter data and of character-string data. 

The "picture specification" is discussed 
in detail in Part II, Section 4, "Picture 
Specification Characters" and in the dis- 
cussion of the PICTURE attribute in Section 
I, "Attributes." 

On input, the picture specification 
describes the form of the data item 
expected in the data stream and, in the 
case of a numeric character string, how its 



arithmetic value is to be interpreted. 
Note that the picture specification should 
accurately describe the data in the input 
stream, including characters represented by 
editing characters. if the indicated char- 
acter does not appear in the stream, the 
CONVERSION condition is raised. 

On output^ the value of the associated 
element in the data list is edited to the 
form specified, by the picture specification 
before it is written into the data stream. 

The PAG E Forma t Item 

The PAGE format item is: 

PAGE 

The paging format item specifies that a 
new page is to be established. It can be 
used only with PRINT files. 

If the specified line is more than three 
lines from the current position then only 
three spaces will be taken when the output 
file is SYSOUT on a terminal. 

General rules: 

1. The establishment of a new page 
implies that the next printing is to 

be on line one. 

2. The PAGE format item has no effect 
unless it is encountered before the 

data list is exhausted. 

The R Format Item 

The R format item is; 

R (statement- label-designator) 

The remote format item allows format 
items in a FORMAT statement to replace the 
remote format item. 

General rules; 

1. The "statement label designator" is a 
label constant or an element label 

variable that has as its value the 

statement label of a FORMAT statement. 

The FORMAT statement includes a format 
list that is taken to replace the for- 
mat item. 

2. The R format item and the specified 
FORMAT statement must be internal to 
the same block. (If the procedure is 
executed recursively, they must be in 
the same invocation.) 

3. There can be no recursion within a 
FORMAT statement. That is, a remote 
FORMAT statement cannot contain an R 
format item that names itself as a 
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U. Any conditions enabled for the GET or 
PUT statement must also be enabled for 
the remote FORMAT statement ts) that 
are referred to. 

5. If the GET or PUT statement is the 
single statement of an on-unit, it 
cannot contain a remote format item. 

The SKIP Format Item 

The SKIP format item is: 

SKIPC (relative~position-of-next-line) ] 

The line skipping format item specifies 
that a new line is to be defined as the 
current line. 

General rules: 

1. The "relative position of next line" 
can be specified by an element expres- 
sion, which is evaluated and converted 
to an integer each time the format 
item is used. It must be greater than 
zero for non-PRINT files. If it is 
not, or if it is omitted, 1 is 
assumed. 

2. The new line is the specified number 
of lines beyond the present line. 

3. If the value of the relative position 
is greater than one, then on input, 
one or more lines will be ignored; on 
output, one or more blank lines will 
be inserted. 

4. The value of the relative position may 
be less than or equal to zero for 
PRINT files only; the effect is that 
of a carriage return without line 
spacing. Characters previously writ- 
ten may be overprinted. 

5. If the SKIP format item is not speci- 
fied at the end of a line, then SKIP 



CD is assumed, that is, single 
spacing. 



For PRINT files, if the specified 
relative position is beyond the limit 
set by the PAGESIZE option of the OPEN 
statement (or the default), the END- 
PAGE condition is raised. 



The SKIP format item has no effect 
unless it is encountered before the 
data list is exhausted. 

If SKIP specifies more than three 
spaces in conversational mode, then 
only three spaces will be taken on 
SYSOUT. 



The X Format Item 

The X format item is: 

X (field-width) 

The spacing format item controls the 
relative spacing of data items in the data 
stream. It is not limited to PRINT files. 

General rules: 

1. The "field width" can be represented 
by an expression, which is evaluated 
and converted to an integer each time 
the format item is used. The integer 
specifies the number of blanks before 
the next field of the data stream, 
relative to the current position in 
the stream. 

2. On input, the specified number of 
characters is spaced over in the data 
stream and not transmitted to the 
program, 

3. On output, the specified number of 
blank characters are inserted into the 
stream. 

4. If the field width is less than zero, 
it is assumed to be zero. 

5. The spacing format item has nc effect 
unless it is encountered before the 
data list is exhausted. 
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SECTION 6: PROBLEM DATA CONVERSION 



This section lists the rules for arith- 
metic conversion and for conversion of 
problem data types. Each type conversion 
is listed under a separate heading. In 
addition to the text, fifteen figures 
appear ; 

• Figures 34 through 38 show the data 
type of the result of an operation 
involving two operands of possibly 
differing types. Note that although 
the tables are for two operands, these 
operands could themselves be the result 
of other operations: any expression 
involving a number of infix operators 
will be eventually reduced, during 
evaluation, to a single infix operation 
with two operands. Note also that the 
result is the result of the expression 
only, and may be converted on subse- 
quent assignment. 

• Figure 39 states the rules for comput- 
ing the precision of the result of an 

arithmetic conversion, 

• Figure 40 states the rules for comput- 
ing the length of the result of an 
arithmetic to character-string 
conversion. 

• Figure 41 states the rules for comput- 
ing the length of the result of an 

arithmetic to bit-string conversion. 

• Figure 42 can be used to find the ceil- 
ing (CEIL) of any value between 1 and 
15 when that value is multiplied by 
3.32 or it can be used to find the 
ceiling (CEIL) of any value between 1 
and 56 when that value is divided by 
3.32. 



in value depends upon the precisions of the 
target and source. In expression evalua- 
tion, the precision of the target is 
derived from the precision of the source. 
In order to estimate and to understand the 
errors that can occur, the precision rules 
irust be understood; and since the rules 
also leave some latitude for the implemen- 
tation, it is helpful to have some know- 
ledge of the way In which conversions are 
implemented. 

Floating-Point Conversion 

In System/360 implementations, both 
decimal and binary floating-point numbers 
are maintained in the internal hexadecimal 
form used in System/360. If the specified 
precision is more than 6 decimal digits, or 
21 binary digits , the number is maintained 
in long floating-point form (14 hexadecimal 
digits with a hexadecimal exponent) . If 
the precision is 6 decimal digits or less, 
cr 21 binary digits or less, the number is 
maintained in short floating-point form (6 
hexadecimal digits and a hexadecimal 
exponent) , 
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Mode Conversion 



Figures 43 through 46 illustrate conv- 
ersion in arithmetic expression opera- 
tions, and they give attributes of the 
results based upon the operator speci- 
fied and the attributes of the two 
operands . 



ARITHMETIC CONVERSION 

The rules for arithmetic conversion spe- 
cify the way in which a value is trans- 
formed from one arithmetic representation 
to another. It can be that, as a result of 
the transformation , the value will change. 
For example, the number .2, which can be 
exactly represented as a decimal fj:,3d- 
point number, cannot be exactly represented 
in binary. The magnitude of such changes 



If a complex value Is converted to a 
real value, the result is the real part of 
the complex value. 

If a real value Is converted to a com- 
plex value, the result is a complex value 
that has the value of the real source as 
the real part and zero as the imaginary 
pa rt . 

Precision Conversi on 

Precision conversion occurs if the spe- 
cified target precision is different from 
the source precision. In particular, there 
always is a precision change when the 
source and target are of different bases. 
It is also possible that there is an actual 
change in precision when converting from 
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floating-point to fixed-pointy because of 
the way in which floating-point numbers are 
represented. Precision changes are per- 
formed by truncation or by padding with 
zeros. Floating-point numbers are con- 
verted from short precision to long preci- 
sion by extending with zeros on the right, 
and from long precision to short precision 
by truncation on the right. 

Fixed-point numbers maintain decimal or 
binary point alignment and may be truncated 
on the left or right, or extended with 
zeros on the left or right. 

No indication is given of loss of signi- 
ficant digits on the right. Loss of digits 
on the left can be checked for if the SIZE 
condition is enabled. In System/360 imple- 
mentations, binary fixed-point numbers are 
stored in words of 31 bits, whatever the 
declared width. Decimal numbers are always 
stored as an odd number of digits, since 
they are maintained in System/360 packed 
decimal format, with the rightmost four 
bits of the rightmost byte expressing the 
sign . 



Attributes of A: 

Value: 

Target: 

Final Value: 

Attributes of A: 

Value: 

Target: 

Final Value: 



FIXED BIN (10,2) 

.1 

FIXED BIN(5,<4) 

.0625 

FLOAT BIN (50) 

-1 

FLOAT BINU) 

•l>value>.0625 



Coded Arithmetic to Numeric Character 

Coded arithmetic data being converted to 
numeric character is converted, if neces- 
sary, to a decimal value whose scale and 
precision are determined by the PICTURE 
attribute of the numeric character iterr. 

Numeric Character to Coded Arithm etic 

Numeric character data being converted 
to coded arithmetic is first interpreted as 
a decimal item of the scale and precision 
determined by the corresponding PICTURE 
attribute. This item is then converted to 
the base, scale, and precision of the coded 
arithmetic target. 



Base Conversion 
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Since the range of binary fixed-point 
numbers is smaller than the range of decim- 
al fixed-point numbers, it is possible for 
significant digits to be lost on the left 
in conversion from decimal to binary. This 
will raise the SIZE condition, but an 
interruption will not occur unless the con- 
dition is explicitly enabled by a SIZE 
prefix. 

The natural notation for constants is 
decimal and, therefore, most constants are 
written in decimal. The precision of a 
constant is derived from the way in which 
it is written. Care should therefore be 
taken when writing noninteger constants 
that will be converted to fixed-point 
binary. 

The following examples illustrate how 
the representation of a decimal constant 
(.1) is converted when used in an arithmet- 
ic expression (such as A+.l). Target 
attributes are derived from the attributes 
of A, the operator, and the atlributes of 
the constant, which are, in this case, 
DECIMAL FIXED (1,1). 



LATA TYPE CONVERSION 

Character-String to Arithmetic 

The source string must represent a valid 
arithmetic constant or complex expression. 
The constant may optionally be signed, and 
may be surrounded by blanks, but cannot 
contain blanks between the sign and the 
value of the constant, or between the end 
of the real part and the sign of the 
imaginary part in a complex expression. 
The permitted forms are; 

[+ |- ) arithmetic-constant 

C+ |- lreal-constantC+ | -limaginary-constant 

A null string gives the value zero. 

The constant will itself have the attri- 
butes of base, scale, mode, and precision. 
It will be converted to conform with the 
attributes of the target. 

Even when converting from character 
string to numeric character field, the 
source must still contain a constant which 
is valid according to the rules for con- 
stants in PL/I source programs. The value 
of this constant is then converted and 
edited to the picture representation. 

The following example will therefore 
result in a conversion error: 

DCL A PICTURE l $$$9V.99 l ; 

A= f $17.95 f ; 
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The currency symbol makes the character- 
string constant invalid for conversion to 
the arithmetic value of the numeric 
;haracter variable, even though its 
character- string value contains a currency 
symbol* 

Correct examples are: 

A= , 17.95 f ; 

A=17.95; 

either of which would result in A having 
the character-string value b$17.95. 

For conversion from character string to 
arithmetic, the attributes assumed for the 
target are those attributes that would have 
been assumed if a fixed- point decimal inte- 
ger of precision (15,0) had appeared in 
place of the string. (The precision given 
lis that for the TSS/360 PL/I compiler.) 

Arithmetic to Character-String 

The arithmetic value is converted to a 
decimal arithmetic constant. The constant 
is inserted in an intermediate character 
string whose length is derived from the 
attributes of the source (see Figure 40, 
"Lengths of Converted character Strings"). 
Except for the base and precision, the 
attributes of the constant are the same as 
the attributes of the source. 

In the case of the conversion of expres- 
sion results, the intermediate string is 
assigned to the target string, and may be 

truncated or padded with zeros on the 

right* 

Since the rules of arithmetic to 
character-string conversion are also used 
for list-directed and data-directed output, 
and for evaluating keys, this type of con- 
version will be found in most programs, and 
should be thoroughly understood. 

Numeric Character to Character-String 

Real numeric character fields are 
treated as character strings and assigned 
to the target string from left to right 
according to the rules for character-string 
assignment. 

The real and imaginary parts of complex 
numeric character fields are concatenated, 
and the resulting string is assigned to the 
target. No character, including I or 
blank, is inserted between or following che 
two parts . 

Fixed-Point to Character-String 

A binary fixed-point source is first 
converted to decimal, and the decimal pre- 



cision is derived from the precision of the 
binary source Csee Figure 39 , "Precision 
for Arithmetic Conversions"). 



A decimal fixed-point source with preci- 
sion (p,q) is converted to character-string 
representation as follows: 



1. If p>^q>=0 (that is, if the assumed 

decimal point lies within the field of 
the internal representation) then; 



• The constant is right adjusted in a 
field of width p+3. 



• Leading zeros are replaced by 
blanks, except for a single zero 
that immediately precedes the decim- 
al point of a fractional number. 

• If the value is negative, a minus 
sign precedes the first significant 
digit (or the zero before the point 
of a fractional number) . Positive 
values are unsigned . 

• Unless the source is an integer, the 
constant has q fractional digits. 

If the source is an integer, there 
is no decimal point. 

If q is negative or greater than p, a 
scaling factor is appended to the 
right of the constant. The constant 
itself is of the same form as an inte- 
ger. The scaling factor has the form: 

F{+ |-lnnn 

where C+|-}nnn has the value -q. 

The number of digits in the scaling 
factor is just sufficient to contain 
the value of q without leading zeros. 

The length of the intermediate string 
is: 

p+3+k 

where k is the number of digits neces- 
sary to represent the value of q (net 
including a sign or the letter F) . 
For example, given: 

DCL A FIXED (4 ,-3) , 
C CHAR(IO) ; 
A=1234.0E3; 
C=A; 

The intermediate string generated in 
converting A would be: 

bl234F+3 
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which, when assigned to C, would give: 

b!234F+3bb 
Other examples are shown in Figure 32. 

Floating-Point to Character-String 

If the source is binary, its binary pre- 
cision is converted to the equivalent 
decimal precision (see Figure 39, "Preci- 
sion for Arithmetic Conversions"). 

The decimal source with precision p is 
converted as if it were transmitted by an E 
format item of the form E(w,d,s) where: 

w f the length of the intermediate 

string, is p+6 (for the F Compiler) 

d, the number of fractional digits, is 
p-1 

s, the number of significant digits, 

is p 

For the TSS/360 PL/I compiler, an E for- 
mat item generates a floating-point decimal 
constant with a signed two-digit exponent. 
(See Part II, Section 5, "Edit-Directed 
Format Items . " ) 

The following examples illustrate the 
intermediate string generated for a 
floating-point to character-string 
conversion: 



Source Attributes : 
Source Value: 
Intermediate String: 

Source Attributes: 
Source Value: 
Intermediate String: 

Source Attributes: 
Source Value: 
Intermediate String: 



FLOAT DEC (6) 

1735x10s 

tl.73500E+08 

FLOAT BIN (20) 

-91882xl0 2 

-9.182200E+06 

FLOAT DEC (5) 

-.0016632 

-1.6632E-03 



Complex to Character-String 

The intermediate string that is 
generated contains a complex expression. 
Its length is 1 plus twice the length of 
the character string generated by a real 
source with corresponding attributes. The 
intermediate string consists of two concat- 
enated strings. The left-hand, or real, 
part consists of a string generated exactly 
as for a real source. The right-hand, or 
xmaginary, part is always signed, and it 
has an I appended. The string lengtn of 
the imaginary part is one character longer 
than the real part (to allow for the I) . 
The resulting string is a complex expres- 



sion, with a sign but no blanks between its 
elements. 

The following examples illustrate the 
intermediate string that results from a 
complex to character-string conversion: 

Source: COMPLEX DEC FLOAT (5) 

Value: 17.3*1.51 

Result: bl«73 00E+01+1.5000E+00I 

Source: COMPLEX DEC FIXED U, 3) 
Value: 0.133+0.0071 
Result: fcfcbO. 133+0. 0071 

Character-String to Bit-string 

The character 1 in the source string be- 
comes the bit 1 in the target string. The 
character in the source string becomes 
the bit in the target string. Any 
character other than and 1 in the source 
string will raise the CONVERSION condition. 
A null character string beqomes a null bit 
string. 

If the source string is longer than the 
target, excess characters on the right are 
ignored (so that excess characters other 
than or 1 will not raise the CONVERSION 
condition). If the target is longer than 
the source, the target is padded on the 
right with zeros. 

Bit-string to Character-String 

The bit becomes the character 0, and 
the bit 1 becomes the character 1. A null 
bit string becomes a null character string. 
The generated character string, which has 
the same length as the source bit string, 
is assigned to the target. 

If the source bit string is shorter than 
the target character string, the remainder 
of the target is padded with blanks. 

The following are examples of bit-string 
to character-string conversion: 



Source Value: 
Target Attributes: 
Result: 

Source Value: 
Target Attributes: 
Result: 

Source Value: 
Target Attributes: 
Result: 

Source Value: 
Target Attributes; 
Result: 



•1011'B 
CBARU) 

•ion 1 

•lOlOl'B 
CHAR (10) VAR 
•10101 f 

•10101-B 

CHAR(IO) 
'lOlOlbbbbb' 

•OOOl'B 

CHAR(l) 
*0 f 



The CONVERSION condition cannot be 
raised on conversion from bit to character; 
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however, a character string created by con- 
version freni a bit string can cause a con- 
version error when reconverted if blanks 
have been inserted. 

Arithmetic to Bit-string 

The absolute arithmetic value is first 
1 converted to a real binary integer, whose 
precision is the same as the length of the 
bit-string target as given in Fxgure 41. 
This integer, without a sign, is then 
treated as a bit string. This intermediate 
string is then assigned to the target. 

Examples are shown in Figure 33. 

B it- st ring to Arithmetic 

For the compiler, the effect is as if 
the bit string were interpreted as an 
unsigned binary integer of maximum preci- 
sion (56,0)- If the string is longer than 
56 bits, bits on the left are ignored: the 
SIZE condition will be raised if nonzero 
bits are lost, provided that SIZE is 
enabled. Note that truncation is on the 
left, not on the right. The null string 
gives the value zero; otherwise, the result 



of a bit-string to arithmetic conversion is 
always positive. 



TABLE OF CEILING VALUES 

Figure 42 is intended to aid the user in 
computing the ceiling values used to deter- 
mine precisions and lengths in conversions. 
It gives the ceiling for the result of a 
multiplication by 3.32 of any value (x) 
between 1 and 15. It also gives the ceil- 
ing for the result of a division by 3.32 of 
any value (y) between 1 and 56. 



TABLES FOR RESULTS OF ARITHMETIC OPERATIONS 

Figures 43 through 46 give the attri- 
butes of the results of arithmetic opera- 
tions, based on the operator specified and 
the attributes of the two operands. In 
these tables, the target precisions (i.e., 
the precisions of the converted operands) 
can never exceed the implementation-defined 
maximums, which, for System/360 .;. p,r Cementa- 
tions, are: 15 for FIXED DECIMAL/ 31 for 
FIXED BINARY, 16 for FLOAT DECIMAL, and 53 
for FLOAT BINARY. 
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CHAR(IO) 
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FIXED 


DEC (5,0) 
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CHAR ( 5 ) 


'bbbb2' 


FIXED 


DEC (4,1) 


| -121.7 




•b-121.7* 




CHAR(7) 
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FIXED 


DEC (4,5) 


| .01217 
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CHAR(7) 


, bl217F- 1 


FIXED 


DEC (4,-3) 


| -3279000 




•-3279F+3' 




CHAR ( 8 ) 


l -3279F+3 i 


FIXED 


DEC (3,3) 


| -.567 




, -0.567 i 




CHAR(6) 


'-0.567* 


FIXED 


BIN(15,0) 


| 4095 




, bbbtb4095« 




CHAR(8) 


'bbbbb409' 


FIXED 


BIN(3,3) 


| .375 




•bb0.3 f 




CHAR ( 4 ) 


«bb0. • 


FIXED 


BIN(15,-15) 


| -65536 




•b-65536F+5» 




CHAR (10) 


, b-65536F+5 l 
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Figure 32. Examples of Conversion From Fixed- Point to Character-String 
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Attributes 
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Target 
Attributes 

BIT (10) 


-+- 


Result 
• 0000001111'B 




FIXED 


BIN(l) 




1 




•1'B 




BIT(l) 
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FIXED 


DEC(l) 
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BIN (3) 




-3 
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BIN (a, 2) 
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'Ol'B 




BITC2) 
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FIXED 


DEC (2,1) 




















FLOAT 


BIN (4) 




1.25 




■OOOl'B 




BITC5) 
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Figure 33. Examples of Conversion From Arithmetic to Bit-string 
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Figure 34. Data Type of Result of Bit- string Operation 
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(NUMERIC CHARACTER | Character string (Character string (Character string (Character string) 
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[CHARACTER STRING [Character string (Character string (Character string] Character string) 

,. x .„„„+. .... x .„ „. + „. i 

(BIT STRING (Character string (Character string (Character string [Bit string | 

l . . X . X „ X . . . . X J 

Figure 35. Data Type of Result of Concatenaticn Operation 
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| Bit string 



(Bit string 
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(Bit string 



j CHARACTER STRING (Bit string 

I. x .„. 

(BIT STRING (Bit string 

j. x.. .„. 

( Note: Although the final result of a comparison operation is always a bit string of 
(length 1, the type of comparison (algebraic, character, or tit) depends on the data 
(type of the intermeidate operands after conversion, which are shown in Figure 37. 

L . ■ ■ r — . 

Figure 36. Data Type of Result of Comparison Operation 
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Figure 37. Data Type of Intermediate Operands of Comparison Operation 
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Figure 38 . Data Type of Result of Arithmetic Operation 



(Source Attributes 



Target Attributes 



Target Precision 



L_ 



DECIMAL FIXED(p r q) 
DECIMAL FIXED (p,q> 
DECIMAL FIXED (p f q) 
DECIMAL FLOAT (p) 
BINARY FIXED (p,q) 
BINARY FIXED <p,q> 
BINARY FIXED (p,q) 
BINARY FLOAT (p) 



DECIMAL FLOAT 
BINARY FIXED 
BINARY FLOAT 
BINARY FLOAT 
BINARY FLOAT 
DECIMAL FIXED 
DECIMAL FLOAT 
DECIMAL FLOAT 



l + p*3.32,q*3,32 (see note 3) 

p*3.32 

p*3*32 

P 

l+p/3.32 r q/3.32 (see note 4) 

p/3.32 

p/3.32 



Notes : 

In the cases of p*3.32 and p/3.32, the CEIL of the result is taken; the value 
taken is an integer that is equal to or greater than the result. 



Target precision never can exceed the implementation-defined maximums, which are 
15 for FIXED DECIMAL, 31 for FIXED BINARY, 16 for FLOAT DECIMAL, and 53 for FLOAT 
BINARY. 



3. When q is negative, the following formula applies: 
(MIN(CEIL(p*3.32)+l,31) , CEIL CABS (q) *3. 32) *SIGN(q>) 

4. When g is negative, the following formula applies: 
(CEIL ( p/ 3. 3 2) +1, CEIL < ABC • q) /3 . 3 2*SIGN <q) ) 

Figure 39. Precision for Arithmetic Conversions 
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[Source Attributes 



I 



Conditions 



I 



) H- 



Target Length 



| DECIMAL FIXED (p # q) 



If p>=q>=0 

If q>p 

or 
q negative 



[DECIMAL FLOAT (p) 

I Numeric character data 



p+3 

p+3+k 

(where k = number of decimal 

digits to express scale 

factor) 

p+6 

Same as source 



j. 

1 Note : Binary data is converted to decimal befcre conversion to character-string. 

L . . . . . 

Figure 40. Lengths of Converted Character Strings (Arithmetic to Character-String) 



j Source Attributes 



Target Length 



[DECIMAL FIXED(p f q) 

I 

[DECIMAL FLOAT (p) 

I 

[BINARY FIXED(p,q) 

I 

[BINARY FLOAT (p) 



(p-q) *3.32 

p*3.32 

p-q 

P 



h 

1 Notes : 

| 1. In the cases of p*3.32 and (p-q)*3.32, the CEIL of the result is taken. 

1 

| 2. If q is greater than or equal to p, the result is a null string. 

L _. . . . . . „ , 

Figure 41. Lengths of Converted Bit Strings (Arithmetic to Bit-String) 
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p| DECIMAL 
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First Operand 



5ECIMAL FIXLD(p 1# qx) | DECIMAL FLOAT ( p ± > j BI NARY FIXEDCpnqs.) (BINARY FLOATCpj,) 



-+• 



- + - 



DECIi-lAL FIXED(p # q) 
P=H-MAX(p 1 -q i ,r: 2 -q 2 ) 

+MAX(q 1# q 2 ) 
q=MAX(q lf q 2 ) 



+- 



DECIMAL FLOAT (p) 
P=MAX( Pll p 2 > 



(EINARY FIXED£p,q) 

| p = l +MAX (p x -q x , r~s) 

( + KAX(q J _,s> 

|q=MAX(q ± ,s) 

| where: 

1 r=l+p 2 *3.32 

| s=q 2 *3.32 



+ - 



BINARY FLOAT (p) 
p=MAX(p 1 , r) 

where; 

r=p 2 *3.32 



DECIMAL FLOAT (p) 

P=MAX(p ± ,p 2 ) 



DECIMAL FLOAT (p) 
p=MAX(p 1# p 2 ) 



[BINARY FLOAT (p) 
| p=MAX(p 1# r) 
| where: 

I r=p 2 *3.32 



BINARY FLOAT (p) 
p=MAX(p ± ,r> 
where : 

r=p 2 *3.32 



- + - 



(BINARY 
(FIXED 
I *F2#q 2 > 



BINARY FIXED(p,q) 
p=l*MAX ( r-s, p 2 -q 2 > 

+MAX(s,q 2 ) 
q=MAX (S , q 2 ) 

where: 

r=l+pi*3. 32 

s=qi*3.32 



BINARY FLOAT (p) 
p=MAX(r, p 2 ) 

where : 

r=pi*3. 32 



(BINARY FIXEDCp,q) 
I p=l + MAX ( p r -q ± , p 2 -q 2 ) 
| +KAX(q 1# q 2 ) 
|q=MAX(q lr q 2 > 



BINARY FLOAT tp) 
p=MAX(p ll p 2 > 



h 



- + - 



-+ 



j BINARY 
FLOAT 
I Cp 2 ) 



BINARY FLOAT (p) 
p=MAX(r , p 2 ) 
where : 

r=p ± *3.32 



BINARY FLOAT (p) (BINARY FLOAT (p) 
p=MAX(r,p 2 ) lF=^AX( Fl ,p 2 ) 
where: | 
r= Fi *3.32 | 
± . 



EINARY FLOAT (p) 
p=MAX(p lf p 2 ) 



Figure 43. Attributes of Result in Addition and Subtraction Operations 
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First Operand 



DECIMAL FIXEDCCi^qi) | DECIMAL FLCAT ( p x ) j BINARY FIXEDCp^qj,) (BINARY FLCATCpi) 



- + - 



DECIMAL FIXED(p f q) 



DECIMAL FLOAT (p) 
p=MAX(p i# p 2 ) 



BINARY FIXED(p,q> 
p=p jL + r+l 
q= q:L +s 
wnere : 

r=l+p 2 *3.32 

s=q 2 *3.32 



BINARY FLOAT (p) 

p=MAXCp 1# r) 
where : 

r=p 2 *3.32 



DECIMAL FLOAT (p) 

p=MAX{p 1# p 2 ) 



DECIMAL FLOAT (p) 
p=KAX(p if p 2 ) 



BINARY FLOAT (p) 

p=MAX(p ir r) 

where: 

r=p 2 *3. 3 2 



BINARY FLOAT (p) 
p=MAX(p ir r> 

where : 

r=p 2 *3.32 



nh 

d | BINARY 
| FIXED 

I *p 2 ,q^ 



I— 

| BINARY 
| FLOAT 
|Cp 2 ) 



- + 



BINARY FIXED(p,q) 

p^=r+p 2 *l 

q=S+q 2 

where : 

r=l+p 1 *3,32 

s=qj.*3. 32 



BINARY FLOAT (p) 
p=MAX(r, p 2 ) 
where : 

r=pi*3.32 



BINARY FIXED(p,q) 

P=P± + P2+1 

q=qa. + q2 



BINARY FLOATCp) 
p=MAX(p ± , p 2 ) 



BINARY FLOAT(p) 

p=MAX(r r p 2 ) 

where: 

r=pi*3.32 



BINARY FLOATCp) 
p=MAXU,p 2 ) 
where : 

r-=p t *3.3 2 



EINARY FLOAT(p) 

p=MAX (p lf p 2 ) 



BINARY FLOATCp) 
p-MAXCp if p 2 ) 



Figure 44. Attributes of Result in Multiplication Operations 
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DECIMAL FIXED(p,q) 

p=15 
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DECIMAL FLOAT (p) 
p=MAX Cp ir p 2 ) 



BINARY FIXED Cp # q) 

p=31 

q=31-( Cp 1 -q 1 >+s) 

where: 

s=q 2 *3.32 



| BINARY FLOAT (p> 
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[where: 

| r=p 2 *3.32 
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DECIMAL FLOAT (p) 
p=MAX(p ±f p 2 ) 



DECIMAL FLOAT (p) 
p=MAX (pi ,p 2 ) 



BINARY FLOAT (p) 

p=MAX(p ±# r) 

where: 

r=p 2 *3.32 



(BINARY FLOAT (p) 

(p=MAX(p 1# r) 

| where: 

| r=p 2 *3.32 



BINARY 

FIXED 

<P 2 #q2> 



h 



BINARY FIXED (p> 

p=31 

q=31- ( (r-s) +q 2 ) 

where: 

r=l+p t *3.32 

s=q±*3. 32 



BINARY FLOAT (p) 

p=MAX(r,p 2 ) 

where: 

r=Pi*3.32 



BINARY FIXEDCp f q) 

p=31 

q=31-((p ± -q ± )*q 2 ) 



(BINARY FLOAT (p) 
|p=MAXCp i# p 2 ) 
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BINARY 
FLOAT 

cp 2 > 
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B I NARY FLOAT (p) 
p=MAX(r, p 2 ) 
where: 

r=p ± *3.32 



BINARY FLOAT (p) 

p=MAX(r,p 2 ) 

where: 

r=p x *3.32 



BINARY FLOAT (p> 
p=MAX(p ± ,p 2 ) 



1 BINARY FLOAT (p) 
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Figure 45. Attributes of Result in Division Operations 
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Case (2) 



Case (3) 



Case (4) 



Case (5) 



Case (6) 



Case (7) 



-T T --• ' 

| Second Operand | 
First Operand | (Exponent) | Target Attributes of Result 

._„. + _. + 

FIXED DECIMAL tp ± , q x > | Unsigned integer (FIXED DECIMAL(p,q) [provided p<15] 

(constant with value n| p= Cpi+1) *n-l 

1 1 q=qi*n 
+ „ + _. _ 

FIXED BINARY ( p ± ,q ± ) (Unsigned integer (FIXED BINARY (p f q) [provided p<31] 

(constant with value n| p=(p 1 +l)*n-l 

1 1 q=qi*n 

x_ .„„ + . 

FIXED DECIMAL (p Xf q ± ) | FIXED DECIMAL ( p 2 , q a ) (FLOAT DECIMAL(p) [unless case CD 
or (or J or (7) is applicable] 
FLOAT DECIMAL (pi) (FLOAT DECIMAL (p 2 ) | p=MAX ( p* , p a ) 

X -„ + _ ... 

FIXED BINARY ( p ± # q ± ) (FIXED DECIMAL ( p 2 ,q 2 ) (FLOAT BINARY(p) [unless case (2) 

or (or | or (7) is applicable] 

FLOAT BINARYtpi) (FLOAT DECIMAL(p 2 ) j p=MAX (p* , CEIL (3 . 32*p 2 ) ) 

X „.+ ..„. ...... 

FIXED DECIMAL (p ± ,q ± ) | FIXED BINARY (p 2 , q 2 ) (FLOAT BINARY ( p) [unless case CI) 
or (or j or (7) is applicable] 
FLOAT DECIMAL(pi) (FLOAT BINARY (p 2 ) | p=MAX (CEILC 3 . 32*p ± ) r p 2 ) 
X_ + . . 

FIXED BINARY ( p ± , q x ) (FIXED BINARY <p 2 , q 2 ) (FLOAT BINARY (p) [unless case (2) 

or (or j or (7) is applicable] 

FLOAT BINARY ( Pi > (FLOAT BINARY (p 2 ) j p=MAX (p^. , p 2 ) 

_ . i. _ _ _ _ x _ ^ . 1 . . 


FLOAT DECIMALCpa.) (FIXED DECIMAL Cp 2 ,0 ) |FLOATCp ± ) [with base of first 
or [or | operand] 
FLOAT BINARY ( pa.) (FIXED BINARY Cp 2f O) | 

X , X , . . __. 



Figure 46. Attributes of Result in Exponentiation Operations 
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SECTION 7: BUILT-IN FUNCTIONS AND PSEUDO-VARIABLES 



All of the built-in functions and 
pseudo-variables that are available to the 
PL/I user are given in this section. The 
general organization of this section is as 
follows: 

1. Computational Built-in Functions 

a. String-handling built-in functions 

b. Arithmetic built-in functions 

c. Mathematical built-in functions 

d. Array manipulation built-in 
functions 

2. Condition Built-in Functions 

3. Based Storage Built-in Functions 

4. Multitasking Built-in Functions 

5. Miscellaneous Built-in Functions 

6. Pseudo-Variables 

The computational built-in functions y 
shown above, provide string handling, ari- 
thmetic operations (addition, division, 
etc.), mathematical operations (tri- 
gonometric functions, square root, etc.), 
and array manipulation. The computational 
built-in functions are: 



Strinq Handlinq: 




BIT 


LOW 


BOOL 


REPEAT 


CHAR 


STRING 


HIGH 


SUBSTR 


I 


TRANSLATE 


INDEX 


UNSPEC 


I LENGTH 


VERIFY 


Arithmetic: 




ABS 


IMAG 


ADD 


MAX 


BINARY 


MIN 


CEIL 


MOD 


COMPLEX 


MULTIPLY 


CONJG 


PRECISION 


DECIMAL 


REAL 


DIVIDE 


ROUND 


FIXED 


SIGN 


FLOAT 


TRUNC 


FLOOR 




Mathematical: 




ATAN 


LOG10 


ATAND 


LOG 2 


ATANH 


SIN 


COS 


SIND 



COSD 








SINK 


COSH 








SCRT 


ERF 








TAN 


ERFC 








TAND 


EXP 








TANH 


LOG 










Array Mani 


pulat 


ion: 




ALL 








LBOUND 


ANY 








POLY 


DIM 








PROD 


HBOUND 








SUM 



The condition built-in functions allow 
the PL/I user to investigate interrupts 
arising from enabled ON- conditions . The 
condition built-in functions are: 



DATAPIELD 
ONCHAR 
ONCODE 
ONCOUNT 



ONFILE 
ONKEY 
ONLOC 
ONSOURCE 



The based storage built-in functions are 
designed to facilitate list processing and 
the use of based storage. They mainly 
return special values which can be assigned 
to locator and area variables. The based 
storage built-in functions are: 



A DDR 
EMPTY 



NULL 

NULLO 



The multitasKinq built-in functions are 
designed to allow the user to investigate 
the current state of a task or asynchronous 
input/output operation, or the current 
priority of a task. Since multitasking is 
not PL/I-controlled in TSS/360, these func- 
tions may only be used successfully to 
investigate input/output operations. The 
multitasking built-in functions are: 

COMPLETION 

PRIORITY 
STATUS 



Since PRIORITY is associated exclusively 
with multitasking, any attempt to irake use 
of it in TSS/360 will result in abnormal 
termination of execution. 



The miscellaneous built-in functions 
perform various duties; for example, one 
function provides the current date, another 
provides a count of data items transmitted 
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during a STREAM input/output operation f 
while another provides an indication of 
whether or not a controlled variable is 
an allocated state. The miscellaneous 
built-in functions are: 



Reference : BIT (expression L, size ]) 



in 



ALLOCATION 

COUNT 
DATE 



LINENO 

TIME 



The section on pseudo- variables gives a 
short discussion for each of the PL/I 
pseudo-variables. A more complete descrip- 
tion can be found in the discussion of the 
corresponding built-in function. The 
pseudo-variables are: 



COMPLETION 
COMPLEX 
I MAG 

ONCHAR 
ONSOURCE 



REAL 

STATUS 

STRING 

SUBSTR 

UNSPEC 



All of the built-in functions and 
pseudo-variables are presented in alphabet- 
ical order under their proper headings. 



COMPUTATIONAL BUILT-IN FUNCTIONS 

STRING HANDLING BUILT-IN FUNCTIONS 

The functions described in this section 
may be used for manipulating strings. 
Unless it is specifically stated otherwise, 
any argument can be an element expression 
or an array expression. If an argument is 
an array, the value returned by the built- 
in function is an array with bounds ident- 
ical to that argument (the function having 
been performed for each element of the 
array) . For those functions where two or 
more array arguments are allowed, the argu- 
ments must have identical bounds. Except 
where stated otherwise, an argument that is 
specified as "string" can be an expression 
of any data type, but if it is arithmetic, 
it is converted to bit-string (if binary 
base) or character-string (if decimal base) 
before the function is invoked. 

All conversions mentioned in this sec- 
tion are made according to the rules for 
the conversion of expression operands as 
specified in Part II, Section 6, "Problem 
Data Conversion." 



BIT String Built-in Function 

Definition : BIT converts a given value to 
a bit string and returns the result to the 
point of invocation. This function allows 
the user to control the size of he result 
of a bit-string conversion. 



Arguments : The ar 



repres 

a bit 

specif 

stant 

"size" 

accord 

given 

Conver 

expres 

of the 



ents the qua 

string. The 
ied, must be 
giving the 1 

is not spec 
ing to the t 
in Part II, 
sion." If 
sion, "size 

array. 



gument "expression" 
ntity to be converted to 
argument "size," when 
a decimal integer con- 
ength of the result. If 
ified, it is determined 
ype conversion rules 
Section 6, "Problem Data 
expression" is an array 
applies to each element 



Result : The value returned by this func- 
tion is "expression" converted to a bit 
string. The length of this bit string is 
determined by the integral value of "size," 
as described above. 

BOOL String Built-in Function 

definition : BOOL produces a bit string 
whose bit representation is a result of a 
given Boolean operation on two given bit 
strings. 

Reference : BOOL (x,y,w) 

Arguments : Arguments "x" and "y" are the 
two bit strings upon which the Boolean 
operation specified by "w" is to be per- 
formed. If "x" and "y" are not bit 
strings, they are converted to bit strings. 
If "x" and "y" differ in length, the short- 
er string is extended with zerps on the 
right to match the length of the longer 
string. 

Argument "w" represents the Boolean 
operation. It is a bit string of length 4 



and is defined as n x n~ 



where each n 



is either or 1. There are 16 possible 
bit combinations and thus 16 possible Bool- 
ean operations. As for "x" and "y," "w w is 
converted to a bit string (of length 4) 
before the function is invoked, if 
necessary. 

If more than one argument is an array, 
the arrays must have identical bounds. 
Note that if only "w" is an array, the 
returned value is an array with identical 
bounds, each element of which is the result 
of the corresponding Boolean operation per- 
formed on "x" and "y." 

Result : The value returned by this func- 
tion is a bit string, z, whose length is 
equal to the longer of "x" and "y." Each 
bit of z is determined by the Boolean 
operation on the corresponding bits of "x" 
and "y" as follows: the ith bit of z is 
set to the value of n x , n a , n 3 , or n 
depending on the combination of the ith 
bits of "x" and "y" as shown in the follow- 
ing Boolean table: 
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XI 



"I" 

I 






o 



-TT- 

II 
- + + - 



++ 



+ + 



+ + 



-J.X- 



- — ^ 



Example : In the following assignment 
statement, assume that U and ID have been 
declared as bit strings, XXX is the string 
■Oll'B, YYY is the string 'HO'B, and the 
Boolean operator is ' 0110'B: 

| U=ID||BOOL (XXX, YYY, ■ 0110'B); 



Further, assume that Z represents the value 
returned to the point at which BOOL is 
invoked (that is, Z is a bit string of 
length 3 that is to be concatenated with 
ID) , then the Boolean table for this invo- 
cation of BOOL can be defined as: 



XXX i 



1 
-+- 



YYYi 






II 



++ 



Zi 



I 

- — 4 



H 



H 



-ii- 



which is interpreted as follows: 

Whenever the ith bits of XXX and YYY are 
and 0, respectively, the ith bit of Z 
is 0; whenever the ith bits of XXX and 
YYY are and 1, respectively, the ith 
bit of Z is 1, and so on. 



Thus, since the 
are and 1, res 
Z is 1; since th 
YYY are 1 and 1, 
bit of Z is 0; a 
XXX and YYY are 
third bit of Z x 
returned to the 
bit string • 101 



first bits of XXX and YYY 
pectively, the first bit of 
e second bits of XXX ana 

respectively, the second 
nd since the third bits of 
1 and 0, respectively, the 
s 1. Therefore, the value 
point of invocation is the 
B. 



CHAR String Built-in Functi on 

Definition : CHAR converts a given value to 
a character string and returns the result 
to the point of invocation. This function 
allows the user to control the size of the 

result of a character-string conversion. 

Reference : CHAR (expression!, size]) 



Arguments : The 
represents the q 
a character stri 
when specified, 
constant giving 
If "size" is not 
mined according 
rules given in P 
Lata Conversion, 
array expression 
element of the a 



argument "expression" 
uantity to be converted to 
ng. The argument "size," 
must be a decimal integer 
the length of the result. 

specified, it is deter- 
to the type conversion on 
art II, Section 6, "Problem 
If "expression" is an 
size" applies to each 
rray . 



Result : The value returned by this func- 
tion is "expression" converted to a charac- 
ter string. The length of this character 
string is determined by "size," as 
described above. 

HIGH String Bu i lt-in Function 

Definition : HIGH forms a character string 
of a given length from the highest charac- 
ter in the collating sequence; that is, 
each character in the constructed string is 
the highest character in the collating 
sequence. 

Reference : HIGH (i) 

Argument : The argument, "i," must be a 
decimal integer constant specifying the 
length of the string that is to be formed. 

Result: The value returned by this func- 
tion is a character string of length "i;* 
each character in the string is the highest 
character in the collating sequence* For 
System/360 implementations, this character 
is stored as hexadecimal FF. 

INDEX String Built-in Function 

Definiti on: INDEX searches a specified 
string for a specified bit or character 
string configuration. If the configuration 
is found, the starting location of that 
configuration within the string is returned 
to the point of invocation. 

Reference : INDEX (string, config) 

Arguments : Two arguments must be speci- 
fied. The first argument, "string," repre- 
sents the string to be searched ,- the second 
argument, "ccnfig," represents the bit or 
character string configuration for which 
("string" is to be searched. If both argu- 
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merits are bit-string, no conversion is per- 
formed. If both arguments are binary, or 
if one argument is bit and one binary, both 
arguments are converted to bit. Otherwise 
both arguments are converted to character. 

If both arguments are arrays, the arrays 
must have identical bounds. 

Result : The value returned by tnis func- 
tion is a binary integer of default preci- 
sion. This binary integer is either: 

1. The location in "string" at which 
"config" has been found. If more than 
one "config" exists in "string," the 
location of the first one found (in a 
left-to-right sense) will be returned. 

2. The value 0, if "config" does not 
exist within "string" or if either of 
the arguments has a length of zero. 

Example : If ASTRING is a character string 
containing: 

• 912NAMEA, 1, FIRST, 2, SECOND' 

then the statement: 

I = INDEX (ASTRING, f l, ') ; 

will return a binary value of ten to the 
point of invocation. This binary value 
represents the location of the configura- 
tion 'I,' within ASTRING. However, if the 
statement had been: 

I = INDEX ( ASTRING, '1') ; 

then a binary value of two would be 
returned to the point of invocation. This 
value is the location of the first • 1" 
appearing within ASTRING. 

LENGTH String Built-in Function 

Definition : LENGTH finds the string length 
of a given value and returns it to the 
point of invocation. 

Reference : LENGTH (string) 

Argument : The argument, "string," repre- 
sents a character string or a bi£ string 
whose length is to be found. The argument 
need not represent a string; if it does 
not, it is converted before the function is 
invoked to a character string (if the argu- 
ment is DECIMAL) or a bit string (if the 
argument is BINARY) . 

Result : The value returned by this func- 
tion is a fixed binary integer of default 
precision giving the current length of 
"string." If "string" is an array expres- 
sion, an array of identical bounds is 
returned. 



Example: If XYZ is a varying-length char- 
acter string whose maximum length is 30, 
but whose current length is 25, then the 
statement: 

I = LENGTH CSUBSTRC XYZ, 4)) ; 

will assign a binary value of 22 to I. 

LOW String Bui lt- in Function 

Definition : LOW forms a character string 
cf specified length from the lowest charac- 
ter in the collating sequence; i.e., each 
character of the formed string will be the 
lowest character in the collating sequence. 

Reference : LOW (i) 

Argument : The argument, "i" must be an 
unsigned decimal integer constant speci- 
fying the length of the string being 
formed. 

Result : The value returned by this func- 
tion is a character string of length "i"; 
each character in the string is the lowest 
character in the collating sequence. For 
System/360 implementations, this character 
is stored as hexadecimal 00. 



REPEAT String Built-in Function 

Definition : REPEAT takes a given string 
value and forms a new string consisting of 
the given string value concatenated with 
itself a specified number of times. 

Reference : REPEAT (string,!) 

Arguments : The argument "string" repre- 
sents a character string pr bit string from 
which the new string will be formed. The 
argument need not represent a string, 
however; if an argument other than a bit 
string or character string is specified, it 
is converted, before the function is 
invoked, to a tit or character string. 

The argument "i" must be an optionally 
signed decimal integer constant. It repre- 
sents the number of times that "string" is 
to be concatenated with itself. 1 

If "string" is an array expression, the 
value of "i" is applied to each element. 

Result : The value returned by this func- 
tion is "string" concatenated with itself 
"i" tiroes. In other words, the returned 
value will be a string containing (i+1) 
occurrences of the value "string." If "i" 
is less than or equal to zero, the returned 
value is identical to the argument (i.e., 
the converted argument, if the original 
argument was not a string) . 
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Example : If BSTR is a bit string contain- 
ing '101*3, the statement 

A = REPEAT (BSTR, 6) ; 

will cause the following value to be 
returned to the point of invocation: 

•1011011 Oil 011011 Oil 01" B 



STRING String Built-in Function 



Definition; 



STRING concatenates all the 



elements in an aggregate variable into a 

I single string element. (STRING can also be 
used as a pseudo-variable.) 

Reference : STRING(x) 

Argument : The argument, "x", is an ele- 
ment, array, or structure variable, com- 
posed either entirely of character strings 
and/or numeric character data, or entirely 
of bit strings. If "x" is an element vari- 
able, the value returned is identical to 
the value of the variable. The argument, 
"x", cannot be an operational expression., 
"x" can be ALIGNED or UNALIGNED; if it is 
ALIGNED, padding is not included in the 
result. 

Result : The value returned by this func- 
tion is an element bit string or character 
string, the concatenation of all the ele- 
ments in "x" . If "x" contains one or more 
varying strings, the result is a varying 
string. For the TSS/360 Compiler there is 
no implementation if x is an element of an 
interleaved array of varying strings, or a 
cross-section of array of structures to 
STRING built-in function. The concatenated 
string in the result has a maximum length 
of 32,767 bytes. 



SUBSTR String Built-in Function 

Definition : SUBSTR extracts a substring of 
user-defined length from a given string and 
returns the substring to the point of invo- 
cation. (SUBSTR can also be used as a 
pseudo-variable. ) 

Reference : SUBSTR (string, i [ , j] ) 

Arguments : The argument "string" repre- 
sents the string from which a substring 
will be extracted. If this argument is not 
a string, it will be converted to a string. 
Argument "i" represents the starting point 
of the substring and "j" represents the 
length of the substring. Arguments "i" and 
"j" must be integers or expressions that 
can be converted to integers. 

If more than one argument is an array, 
the arrays must have identical bounds. 



Assuming that the length of "string" is 
k, arguments "i" and " j w must satisfy the 

following conditions: 

1. j must fce less than or equal to k and 

greater than or equal to 0. 

2. i must be less than or equal to k and 
greater than or equal to 1. 

3. The value of i+j-1 must be less than 
or equal to k. 

Thus, the substring, as specified by w i" 
and "j" irust lie within "string." 

If "j" is not specified, it is assumed 
to be equal to the value of k-i+1. In 
other words, it is assumed to be the length 
of the remainder of "string," beginning at 
the ith position in "string. " 

When these conditions are not satisfied, 
the SUBSTR reference causes the STRINGRANGE 
condition to be raised, if it is enabled. 
If STRINGRANGE is not enabled, the result 
cf the erroneous reference is undefined. 

Result : The value returned by this func- 
tion is a varying- length string whose cur- 
rent length is defined as follows: 

1. If j=0, the returned value is the null 
string. 

2. If j is greater than 0, the returned 
value is that substring beginning at 
the ith character or bit of the first 
argument and extending j characters or 
bits. 

3. If j is not specified, the returned 
value is that substring beginning at 
the ith character or bit and extending 
to the end of "string." 

Example : If AAA is a character string of 
length 30, the statement: 

ITEM = SUBSTR (AAA, 7, 14); 

will cause a 14-character substring to be 
extracted irora AAA, starting at the seventh 
character of AAA, The extracted string is 
then returned to the point of invocation, 
after which it is assigned to ITEM. 



The TRANSLATE String Built-in Function 

Definition : TRANSLATE returns the trans- 
lated value of a specified string to the 
point of invocation. The translation is 
performed in accordance with a translation 
table supplied in the form of two arguments 
to the function. 

Reference : TRANSLATE! s , r [ , pi) 
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Arguments : "s" repre 
string; i.e., the str 
value to be translate 
«p« represent the rep 
strings respectively; 
character map front n r 
translation table. I 
tied, an implenientat i 
string is provided; f 
compiler, this string 
EBCDIC characters arr 
order, hexadecimal 00 



ents the source 
ing that supplies the 
d. Arguments "r" and 
laceroent and position 

a character-for- 
onto "p" defines the 
f "p" is not speci- 
on-defined character 
or the TSS/360 PL/I 

consists of the 256 
anged in ascending 

through FF. 



If any argument is arithmetic, it is 
converted to string; a character string if 
the argument is DECIMAL, a bit string if 
the argument is BINARY. If, after any 
arithmetic-to-string conversion, all argu- 
ments are bit strings, or all are character 
strings, no further conversion takes place; 
otherwise, bit-string arguments are con- 
verted to character strings. 

When n r n is shorter than " p M , it is 
right-padded (with blanks or 0*s, depending 
on the string type) to the length of V . " 



Result : The value returned by this func- 
tion is a string identical in length and 
value to the source string, M s." A change 
is made to the source string only when a 
character/bit position of n s* contains a 
character or bit that has been specified 
for replacement (by inclusion of that value 
in the position string "p"); that value 
will be replaced by the corresponding value 
from the replacement string "r." The 
correspondence is by position: character/ 
bit positions l,2,3,...,n of " p w correspond 
respectively to character/bit positions 
1, 2, 3, . . . , n or "r. " 



Example : 



I Note : Use of the function will in rrany 
cases result in the inline use of the TR 
I machine instruction. 



UNSPEC String B uilt- i n Function 



Definition : UNSPEC returns a bit string 
that is the internal coded representation 
of a given value. (UNSPEC can also be used 
as a pseudo-variable.) 

Reference : UNSPEC (x) 

Argument : The argument, "x," may be an 
arithmetic or string constant, variable, or 
expression, or an area, pointer, or offset 
variable, whose internal coded representa- 
tion is to be found. 

Result : The value returned by this func- 
tion is the internal coded representation 
of "x." This representation is in bit- 
string form. The length of this string 
depends upon the attributes of "x," and is 
defined by System/360 implementations as 
follows : 



If 



is FIXED BINARY of precision 



DECLARE (S,T) CHAR(IO), 
(P,R) CHAR(3); 



(p,q), the length is as follows: 

a. If p < 16 and the argument is a 
single variable, the length is 16. 

b. If p < 16 and the argument is not 
a single variable, the length is 
32. 

c. If p > 15 the length is 32. 

If "x" is FIXED DECIMAL of precision 
(^ f q), the length is defined as 8* 
FLOOR ((p+2)/2). 

If "x M is FLOAT BINARY of precision p, 
the length is 



P=\.$\- 

R= f . ,D\- 

GET DATA (S) ; 

T=TR ANSLATE ( S , R , P ) ; 

PUT DATA (T) ; 

GO TO A; 



That sequence 
translates comma 
commas, and doll 
• D* , and writes 
Thus, if the str 
read in, the str 
written out. (I 
can be achieved 
consist of the E 
the replacement 
dollar sign by t 



reads in data from SYSIN, 
s to periods, periods to 
ar signs to the character 
out the result on SYSOUT. 
ing S='$12, 345.50" vere 
ing TD12. 345,50' would be 
n TSS/360, the same result 
by omitting P and making R 
BCDIC sequence, xcept for 
of the comma, period, and 
he period, comma, and 'D*.) 



a. 32, if p is less than or equal to 
21. 

b. 64, if p is greater than 21. 

If "x" is FLOAT DECIMAL of precision 
p, the length is 

a. 32, if p is less than or equal to 
6. 

b. 64, if p is greater than 6. 

If "x" is a character-string of length 
n or a numeric character data item 
whose character-string value is of 
length n, the length is 8*n. 

If "x" is a bit-string of length n, 
the length is n. 
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7. If "x" is complex, the length is twice 
that of the corresponding real value. 

8. If "x" is a pointer, the length is 32. 

9. If m x m is an offset, the length is 32. 



GT X s , the returned value is 0; if A = 'P > 
X', the value is 3). 

Note : Use of this function will in many 



cases result in the inline use of the TRT 

machine instruction. 



10. If "x" is an area of size n, the 
length is 8*(n+16) . 

The VERIFY String Built-in Function 

Definition ; VERIFY examines two given 
strings and returns a fixed binary if 
each character or bit in the first string 
Is represented in the second string; other- 
wise, the value returned is the index of 
the first character in the first string 
that is not represented in the second 
string. 

Reference ; VERIFY (expr~l, expr-2) 

Arguments ; "expr-1" and " expr-2" represent 
the source and verification strings respec- 
tively. If either argument is arithmetic, 
it is converted to string; a character 
string if the argument is DECIMAL, or a bit 
string if the argument is BINARY, If after 
any arithmetic-to-string conversion has 
been performed, both arguments are bit 
strings or both character strings, no 
further conversion takes place; otherwise, 
the bit-string argument is converted to a 
character string. 

Result ; The value returned by this func- 
tion is a fixed binary integer of default 

precision (15,0) . 

Each character or bit, c, of the source 
string is examined to see if it is repre- 
sented in the verification string; to 
determine if 

INDEX(expr-2,c)-,=0 

The characters or bits of the source 
string are examined from left to right. If 
a character or bit is not represented in 
the verification string, the return is the 
index of that character or bit in the 
source string. If each character or bit in 
the source string is represented in the 
verification string, the returned value is 
0. 

Example ; B is a character string, length 
48, containing the 48 characters of the 
4 8-character set. The expression; 

VERIFY (A, B) 

will return a value of for any value of A 
that consists solely of characters ;rom the 
48-character set, but will index the first 
character in a value of A that does not 
conform to the 4 8-character set (if A = *P 



ARITHMETIC BUILT-IN FUNCTIONS 

All values returned by arithmetic built- 
in functions are in coded arithmetic forrr. 
The arguments of these functions should 
also be in that form. If an argument is 
not coded arithmetic, then, before the 
function is invoked, it is converted to 
coded arithmetic according to the rules 
stated in Part II, Section 6, "Problem Data 
Conversion." Note, therefore, that in the 
function descriptions below, a reference to 
an argument always means the converted 
argument, if conversion was necessary. 

In some function descriptions, the 
phrase "converted to the highest charac- 
teristics" Is used; this means that the 
rules for mixed characteristics are fol- 
lowed. (For these rules, refer to the sub- 
ject "Data Conversion in Arithmetic Opera- 
tions" in Part I, Section 4, "Expressions 
and Data Conversion".) 

In general, an argument of an arithmetic 
built-in function may be an element or 
array expression. If an argument is an 
array, the value returned by the built-in 
function is an array of the same dimension 
and bounds as the argument (the function 
having been performed once for each element 
of the array). Thus, for example, if an 
array argument is passed to the absolute 
value function ABS # the returned value is 
an array, each element of which is the 
absolute value of the corresponding element 
in the argument array. 

Unless it is specifically stated 
otherwise: 

1. The mode of an argument may be real or 

COITiplfX. 

2. The base, scale, mode, and precision 
of the returned value are determined 
according to the rules for the conver- 
sion of expression operands as given 
in Part II, Section 6, "Probleir Data 
Conversion." 

In many of these built-in functions , the 
symbol N is used. This symbol represents 
the maximum precision that a value rray 
have. It is defined, for System/360 imple- 
mentations, as follows; 

N is 15 for FIXED DECIMAL values 
16 for FLOAT DECIMAL values 
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31 for FIXED BINARY values 
53 for FLOAT BINARY values 



"q"; this precision is maintained through- 
cut the execution of the function. 



The precision of decimal 
floating-point items should 
using the built-in functions 
DECIMAL, DIVIDE, FLOAT, MULT 
CISION. For decimal floatin 
if the precision is less tha 
(6) , short floating-point fo 
the precision is greater tha 
floating-point form is used, 
floating-point items: if th 
less than or equal to (21), 
point form is used; if the p 
greater than (21), long floa 
is used. 



and binary 
be noted when 
ADD, BINARY, 
IPIY, and PRE- 
g- point items: 
n or equal to 
rm is used; if 
n (6) f long 

For Binary 
e precision is 
short floating- 
recision is 
ting -point form 



ABS Arithmetic Built-in Function 

Definition : ABS finds the absolute value 
of a given quantity and returns it to the 
point of invocation. 

Reference : ABS (x) 

Argument : The quantity whose absolute 
value is to be found is given by "x. w 

Result : The value returned by this func- 
tion is the absolute value of "x." If "x" 
is real, the result is the positive value 



of "x w ; if 



'x" 



is complex, the result is 



the positive square root of the sum of 
squares of the real and imaginary parts of 
"x. " The mode of the result is real, while 
the base, scale, and precision are the same 
as those of "x," with one exception: if 
"x" is a complex fixed-point value of pre- 
cision (p,q), the precision of the result 
is : 

(MIN(N,p+l) ,q) 

ADD Arithmetic Built-in Function 

Definition : ADD finds the sum of two given 
values and returns it to the point of invo- 
cation. This function allows the user to 
control the precision of the result of an 
add operation. 

Reference : ADD (x ff y,p[ f ql) 



Arguments : Arguments "x 
the values to be added. 
"q" must be decimal integ 
ifying the precision of t 
be signed. If the scale 
fixed-poinb, both "p" and 
cified; if the scale of t 
floating-point, only "p" 
In either case, w p" must 



and "y" represent 
Arguments "p n and 
er constants spec- 
he result; "q" may 
of the result is 

q" must be spe- 
he result is 
must be specified. 
not exceed N. 



Result : The value returned by this func- 
tion is the sum of "x" and "y." The preci- 
sion of the result is determined by "p" and 



BINARY Arithmetic Built-in Function 

Definition : BINARY converts a given value 
to binary base and returns the converted 
value to the point of invocation. This 
function allows the user to control the 
precision of the result of a binary 
conversion. 

Reference : BINARY Cx(,p[,q]]) 

Arguments : The first argument, "x," repre- 
sents the value to be converted to binary 
base. Arguments "p w and "q, n when speci- 
fied, must be decimal integer constants 
giving the precision of the binary result; 
m q m may be signed. The precision of a 
fixed-point result is (p,q) ; the precision 
of a floating-point result is (p) . If both 
"p" and M q w are omitted, the precision of 
the result is determined according to the 
rules given for base conversion in Part II, 
Section 6, "Problem Data Conversion." Note 
that m q m must be omitted for floating-point 
arguments. 

Result : The value returned by this func- 
tion is the binary equivalent of "x." The 
scale and mode of this value are the same 
as those of "x. w The precision is given by 

w p w and "q." 



CEIL Arithmetic Built-in Function 

Definition : CEIL determines the smallest 

integer that is greater than or equal to a 

given real value and returns that integer 
to the point of invocation. 



Reference: CEIL (x) 



Argument : 
complex. 



The argument, 



must not be 



Result : The value returned by this func- 
tion is the smallest integer that is great- 
er than or equal to "x." The base, scale, 
mode, and precision are the same as those 
of "x, with one exception: if "x" is a 
fixed-point value of precision (p f q), the 
precision of the result is defined as: 

(MIN(N r MAX(p-q+l,l>) ,0) 



COMPLEX Arithmetic Built-in Function 

Definition : COMPLEX forms a complex number 
from two given real values and returns it 
to the point of invocation. (COMPLEX can 
also be used as a pseudo-variable.) 



Reference : COMPLEX (x,y) 
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Arguments : Arguments w x" and "y" must both 
be real; "x w represents the real part of 
the complex number to fce formed and "y" 
represents the imaginary part. 

Result : The value returned by this func- 
tion is the complex number that has been 
formed from w x w and "y.* 



CONJG Arithmetic Built-in Function 

Definition : CONJG finds the conjugate of a 
complex value and returns it to the point 
of invocation. (The conjugate of a complex 

number is the complex number with the sign 

of the imaginary part reversed.) 



Reference : 



CONJG Cx) 



Argument : The argument, w x," is the value 
whose conjugate is to be found? it must be 

complex. 

Result : The value returned by this func- 
tion is the conjugate of "x. " The base, 

scale, mode, and precision of the conjugate 
are the same as those of the argument, 

DECIMAL Arithmetic Built-in Function 



Reference : DIVIDE Cx,y,pC,q]) 

Arguments : The argument, "x," is the divi- 
dend and argument "y" is the divisor. 
Arguments w p w and "q" ("q" is optional and 
may be signed) must be decimal integer con- 
stants specifying the precision of the 
result. If the result is a fixed-point 
value, w p" and "q" must both be specified; 
if the result is a floating-point value, 
only "p" must be specified. In either 
case, n p M roust not exceed N. 

Result : The value returned by this func- 
tion is the quotient resulting from the 
division of "x" by "y." The precision of 

the result is determined by m p m and "q w as 

described above; this precision is main- 
tained throughout the execution of the 
function. 



FIXED Arithmetic Built-in Function 

Definition : FIXED converts a given value 
to fixed-point scale and returns the con- 
verted value to the point of invocation. 
This function allows the user to control 
the precision of the result of a fixed- 
point conversion. 



Definition : DECIMAL converts a given value Reference: FIXED (x[,pl,q]j) 



to decimal base and returns the converted 
value to the point of invocation. This 

function allows the user to control the 
precision of the result of a decimal 
conversion. 

Reference : DECIMAL (xC,p[ # q]J) 

Arguments : The first argument, "x," repre- 
sents the value to be converted to decimal 
base. Arguments "p w and "q, n when speci- 
fied, must be decimal integer constants 
giving the precision of the decimal result; 
"q" may be signed. The precision of a 
fixed-point result is (p,q); the precision 
of a floating-point result is Cp) . If both 
"p" and "q" are omitted, however, the pre- 
cision of the result is determined accord- 
ing to the rules given for base conversion 
in Part II, Section 6, "Problem Data Con- 
version," Note that w q" must be omitted 
for floating-point arguments. 

Result : The value returned by this func- 
tion is the decimal equivalent of the argu- 
ment "x"; its precision is given by "p" and 
"q." 



Argument ; The first argument, "x, CT repre- 
sents the value to be converted to fixed- 
point scale. Arguments "p" and "q," when 

specified, must be decimal integer con- 
stants ("q" can be signed) giving the pre- 
cision of the result, (p,q). For System/ 
360 implementations, if "p M and "q" are 

emitted, "p" is assumed to be 15 for binary 
m x n and 5 for decimal "x"; n q K is assumed 

to be 0. 

Result : The value returned by this func- 
tion is the fixed-point equivalent of the 
argument "x"; its precision is (p,q). 



FLOAT Arithmetic Built-in Function 

Definition : FLOAT converts a given value 
to floating-point scale and returns the 
converted value to the point of invocation. 
This function allows the user to control 
the precision of the result of a floating- 
point conversion. 

Reference : FLOAT C x C , p ] ) 



DIVIDE Arithmetic Built-in Function 

Definition : DIVIDE divides a given value 
by another given value and returns the quo- 
tient to the point of invocation. This 
function allows the user to control the 
precision of the result of a divide 
operation. 



Arguments : The first argument, ^x," repre- 
sents the value to be converted to 
floating-point scale. The second argument, 
"p," when specified, must be a deciiral 
integer constant giving the precision of 
the result. For System/360 implementa- 
tions, if "p** is omitted, it is assumed to 
be 21 for binary M x" and 6 for decimal w x. w 
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Result : The value returned by this func- 
tion is the floating-point equivalent of 
m K m i its precision is "p** 



FLOOR A ri thmetic Built-in Func tion 

Definition : FLOOR determines the largest 
integer that does not exceed a given value 

and returns that integer to the point of 

invocation. 



Reference: FLOOR (x) 



Argument : 
complex. 



The argument, m x t m must not be 



Result : The value returned by this func- 
tion is the largest integer that does not 
exceed "x." The base f scale, mode, and 

precision of this value are the same as 
those of *x, " with one exceptions if •x" 
is a fixed-point value of precision (p,q) v 

the precision of the result is: 

CMINCN f MAX(p~q*l f 1)) ,0) 



IMAG Arithmetic Built-in Function 

Definition : IMAG extracts the imaginary 
part of a given complex number and returns 
it to the point of invocation. C IMAG can 

also be used as a pseudo- variable. > 

Reference : IMAG (x) 

Argument ; The argument, *"x," is the com- 
plex value whose imaginary part is to be 
extracted* 

Result: The value returned by this func- 
tion is the imaginary part of "x." The 
base, scale, and precision of the imaginary 
part are unchanged. The mode of the 
returned value is real. 

MAX Arithmetic Built-in Function 

Definition : MAX extracts the highest- 
valued expression from a given set of two 
or more expressions and returns that value 
to the point of invocation. 

Reference : MAX Cx ± , x ai . . . ,x n ) 

Arguments : Two or more arguments must be 
given. The arguments must not be complex. 

Result : The value returned by MAX is the 
value of the maximum- valued argument* The 
returned value is converted to conform to 
the highest characteristics of all the 
arguments that were specified. If the 
arguments are fixed-point valuri and have 
precisions : 

*P:l#<1jl*# Cp a qa>f--«f (Pnr<2n) 



then the precision of the result is as 
follows: 

C MIN CN, MAX (pi-q*, . . • , Pn-qn> * 

MAXCqj! , ... r qn)) f MAXIq s . f . . *q n >) 

MLXJN Arithmetic Built-in Function 

Definition ; MIN extracts the lowest- valued 
expression from a given set of two or more 
expressions and returns that value to the 
point of invocation- 
Reference : MIN { x ± , x a # . * * f x n ) 

Arguments : Two or more arguments must be 
given. The arguments must not be complex. 

Result : The value returned by MIN is the 
value of the lowest- valued argument. The 

returned value is converted to conform to 
the highest characteristics of all the 
arguments that were specified* If the 
arguments are fixed-point values and have 
precisions: 

Cp±#qj„> t Cp a# q a ), . • ., Cpn, qn) 

then the precision of the result is as 
follows: 

(MlN(N f MAXfp ± -q jL# .• . »Pn~%i>* 

MAX (q j. f . . *q n ) > # MAX Cq A f . • . , q n > ) 

MOD Arithmetic Bui lt-in_ Function 

Definition : MOD extracts the remainder 
resulting from the division of one real 
quantity by another and returns it to the 
point of invocation. 

Reference : MOD tx ±i x a ) 

Arguments : Two arguments must be given* 
They must not be complex. Before the func- 
tion is invoked, the base and scale of each 
argument are converted according to the 
rules for the conversion of expression 
operands, as given in Part II, Section 6, 
"Problem Data Conversion.* 

Result s The. value returned by MOD is the 
lowest possible positive value, x 3f such 
that: 

(x A -x 3 )/x a =n 

where n is an integer. 

In other words, the value returned is the 
smallest positive number that must be sub- 
tracted from the first argument in order to 
make it exactly divisible by the second 
argument. This means that if the first 
argument is positive, the returned value is 
the remainder resulting from a division of 
the first argument by the second* if the 
first argument is negative, the returned 
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value is the modular equivalent of this 
remainder. CFor example, MODC29,6) returns 
the v-i"j;;ie 5 # while MOD (-29, 6) returns the 
value I.) 

It t.;-i/- result is in floating-point 

scale, it 3 precision is the higher of the 
precisions of the arguments; if the result 

is in fixed-point scale, its precision is 
defines ..* :• follows? 

i r.\tt CN, Pa-qa + MAX C q A , q a ) ) , MAX (q ±g q a ) > 

where i'g* ,q±) and Cp a ,q a ) are the precision 
of m a A _ *' <hi i\d * x a , " res pect ively . 

If the Mlue of the second argument is 
zero, the ZERODIVIDE condition is raised. 

Note: Mhen the MOD function is used with 
FIXED artuments of different scale factors f 
the results may be truncated. If SIZE is 
enabled, an error message will be printed? 
if SIZE is disabled, no error message will 
be printed and the result is undefined. 

*&}J±1 1 i-U;.{ J'li-thmetic Bail! -in F unc tion 

Defin ition: MULTIPLY finds the product of 
two given values and returns it to the 
point of invocation. This function allows 
the user to control the precision of the 
result of a multiplication operation. 

Reference : MULTIPLY (x ± , x a , pE ,q] ) 

Arguments : Arguments m x ± m and "x a * repre- 
sent the values to be multiplied. Argu- 
ments w p" and *q" C"q" is optional and may 

be signed) are decimal integer constants 
specifying the precision of the result* if 
the result is a fixed-point value, "p" and 
"q* imist both be specified; if the result 
is a floating-point value , only "p" must be 
specified. In either case, "p" must not 
exceed N. 

Result: The value returned by this func- 
tion is the product of "x^" and *x a ." The 

precision of the result is as specified; 
this precision is maintained throughout the 
execution of the function. 

PRECI SION Arithmetic Built-in Function 

Defin ition: PRECISION converts a given 
value to a specified precision and returns 
the converted value to the point of 

invocation. 

Refere nce : PRECISION (x,p( f q]) 

Argument s i The first argument, "x," repre- 
sents the value to be converted to the spe- 
cified precision. Arguments "p 8 and "q" 
("q" is optional and may be signed) are 
decimal integer constants specifying the 
precision of the result. If "x* is a 



fixed- point value, 



and 



must be spe- 



cified; if "x 8 * is a floating-point value, 
only 

Result : The value returned by this func- 



tion is the value of 



converted to the 



specified precision. The base, scale, and 
mode of the returned value are the same as 
those of m x« m 

REAL Arithmetic Built-in Function 

Definition : REAL extracts the real part of 
a given complex value and returns it to the 
point of invocation. (REAL can also be 
used as a pseudo-variable. 5 

Reference : REAL i x ) 

Argument : The argument, "x," must be a 
complex expression - 

Result : The value returned by this func- 
tion is the real part of the complex value 
represented by "x. w The base, scale, and 
precision of the real part are unchanged. 

ROUND Arithmetic Built-in Function 

Definition : ROUND rounds a given value at 

a specified digit and returns the rounded 
value to the point of invocation* 

Reference : ROUND (expression, n> 

Arguments ; The first argument, "expres- 
sion,® is an element or array representing 
the value Cor values, in the case of an 
array expression) to be rounded; the second 
argument, m n g m is a signed or unsigned 
decimal integer constant specifying the 
digit at which the value of "expression* is 
to be rour/ded. If ^n" is positive, round- 
ing occurs at the nth digit to the right of 
the decimal Cor binary) point in the value 
of * expression"; if "n* is zero, rounding 
occurs at the first digit to the left of 
the decimal Cor binary) point in the value 
of ^expression 1 *; if "n w is negative, round- 
ing occurs at the nth*l digit to the left 
of the decimal Cor binary) point in the 
value of "expression- " Note that the 
decimal (c^ binary) point is assumed to be 
at the 1'^ft for floating-point values* 

Resu.- 1: For fixed -point values, ROUND 
returns the value of "expression" rounded 
at the nth digit to the right of the deci- 
mal Cor binary) point, for positive m n m , or 
at the first digit to the left of the deci- 
mal Cor binary) point for zero •»• , or at 
the nth*l digit to the left of the decimal 
Cor binary) point for negative or zero "n". 
Thus, when m n m is negative, the returned 
value is an integer. 

If "expression* is a floating-point ex- 
pression, the second argument is ignored, 
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and the rightmost bit in the internal 
floating-point representation of the expre- 
ssion's value is set to 1 if it is 0. it 
the rightmost bit is 1, it is; left 
unchanged. 

it "expression" is a string, tin- 
returned value is the same siting 
unmodified. 

The base ff scale, and mode ot the? 
returned value are those of the value of 
"expression". 



Argumen t : The argument, 

complex. 



•x, " must not be 



The pr 
floating 
pression 
value for 
<p+l,N),q 
returned 
is to ail 
ing would 
expressed 
ROUNDC9.9 



ecision of the 

point expressio 

; the precision 

fixed-point ex 

) . The extra d 

value for fixed 

ow for those ca 

give a result 

in " p" digits, 

99,2) would res 



returned 
ns is tha 

ot the r 
pressions 
igit (p*l 
-point ex 

seu in wh 

that coul 

tor exaii. 

ult in 10 



value for 
t of "ex- 
etuxned 

is CMIN 
) of the 
pressions 
ich round- 
el not be 
pie, 
.000. 



Note that the rounding ot a negative 
quantity results in the rounding of the 
absolute value of that quantity. 



oIGN Arithmetic Built-in Funct ior i 

Definition : SIGN determines whether a 
value is positive, negative, or zf.ro, and 
it returns an indication to the |oint ot 
invocation. 

Reference : SIGN (x) 

Argument : The argument, "x," must not be 
complex. 

Result : This function returns a real 
fixed-point binary value of default preci- 
sion according to the following rules: 

1. If the argument is greater than 0, the 
returned value is 1. 

2. If the argument is equal to zero, the 
returned value is 0. 

3. If the argument is less than zero, the 
returned value is -1. 

TRUNC Arithmetic Built-in Function 

Definition : TRUNC truncates a given value 
to an integer as follows: first, it deter- 
mines whether a given value is positive, 
negative, or equal to zero. If the value 
is negative, TRUNC returns the smallest 
integer that is not less than that value; 
if the value is positive or equal to zero, 
TRUNC returns the largest integer that does 
not exceed that value. 



Res ult ; 11 "x" is less than- zero, the 
value returned by TRUNC is CEIL(x). If "x" 
is greater than or equal to zero, the value 
returned by TRUNC is FLOOR (x). In either 
case, t he base, scale, and mode of the 
result are the same as those of "x." If 
"x* is a floating-point value, the preci- 
sion remains the same. If "x" is a fixed- 
point value of precision (p,q), the preci- 
sion ot the result is: 

(MIN(N,H.AX(p-q + l,l > > ,0) 



MATHEMATICAL BUILT-IN FUNCTIONS 

All arguments to the mathematical built- 
in functions should be in coded arithmetic 
form and in floating-point scale. Any 
argument that does not conform to this rule 
is converted to coded arithmetic and 
floating-point before the function is 
invoked, according to the rules stated in 
Part 11 f Section 6, "Problem Data Conver- 
sion." Note, therefore, that in the func- 
tion descriptions below, a reference to an 
argument always means the converted argu- 
ment, it conversion was necessary. 



In general 
cal tuilt-in 
array express 
array, the va 
function is a 
and bounds as 
having been p 
cf the array) 
to the cosine 
array, each e 
cf the corres 
itent array 



, an argument to a mathemati- 
function may be an element or 
ion. If an argument is an 
lue returned by the built-in 
n array of the same dimension 

the argument (the function 
erformed once for each element 
Thus, for example, an array 

function COS results in an 
lement of which is the cosine 
pending element in the argu- 



Unless it is specifically stated other- 
wise, an argument may be real or complex. 
Figure 47 at the end of this section pro- 
vides a quick reference for those mathemat- 
ical functions that accept either real or 
complex arguments and those that accept 
only real arguments. 

All of the mathematical built-in func- 
tions return coded arithmetic floating- 
point values. The mode, base, and preci- 
sion of these values are always the same as 
those of the arguments. 

ATAN Mathematical Built-in Function 

Definition : ATAN finds the arctangent of a 
given value and returns the result ex- 
pressed in radians, to the point of 
invocation. 



Reference: TRUNC Cx) 



Reference : ATAN (x[,yl) 
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r .. — — . T . . . T , 

(Function Reference! Argument Type j 



Value Returner! 



Error Condition! 



ATANCx) 



real 



complex 



arctanCx) in radians 
- C pi/2)<ATAN Cx) <pi/2 



-i*ATANH(i*x) 



±li 



ATANCx,y) 



both real 



see function 
description 



error if 
x^O and y=0 



ATANDCx) 



real 



arctan(x) in degrees 
-90<ATANDCx)<9 



ATANDCx, y) 



both real 



see function 
description 



error if 

x=0 and y=0 



ATANriCx) 



real 



arctanh (x) 



ABS(x)>l 



complex 



(LOG! (l*x)/<l~x)))/2 



±1 



H- 



C(»J(x) 

x in radianc 



real 
complex 



cosine (x) 



cos(y^)*cosh (y^) 
~i*sin (y*) *sinh (y 2 ) 



COSD(x) 

x in degrees 



real 



cosine (x) 



COSH(x) 



real 
complex 



coshCx) 



cosh (y % > *cos Cy^») 

♦ i*sinh Cy*) *sin (y 2 ) 



IT f» 

xTIJa 



ERF(x) 



real 



dt 



ERFCCx) 



real 



1 - ERMx) 



EXPCx) 



real 



corr.pl ox 



r— 



LOGCx) 



real 
complex 



log (x) 



x<;o 



log (x) = w 
where w = u±i*v 

and ~p. i<v<pi 



x=0 



LOG10 Cx> 



real 



log A (x) 



x<0 



LOG2(x) 



real 



log^ Cx) 



x«T0 



SINCx) 

x in radians 



real 
complex 



~» i n < x > 



sin(y x > *co.sh (y^> 

♦ i*cos (y* )*sinhCy^> 



SIND(x) 

x in degrees 



real 



sin(x) 



SINH(x) 



real 

complex 



sinh(x) 



sinh C y 3L> *cos Cy^) 

+ i*coshCy 1 )*j;in(y -2 > 



Figure ^*7. Mathematical Duilt-In Functions (part 1 of 2) 
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[Function Reference 



-t- 



Argument Type | Value Returned 



Error Conditions 
x«3 



SQRT(x) 



real 



complex 



U/x" = w 

(where w = u±i*v 
(and either u>G, or 
| u=0 and v>0 



I 

i 



TAN ( x ) 

x in radians 



real 



| tangent (x) 



complex 



| tangent (x) 



-+- 

i 

I 
-+- 



TAND(x) 

x in degrees 



real 



| tangent (x) 



TANH(x) 



real 

complex 



| tanh (x) 

-+ 

| tanh (x) 



I 

-JL- 



Figure 47. Mathematical Built-in Functions (Part 2 of 2) 



Arguments ; The argument "x" must always be 
specified; the argument "y" is optional. 
If w y" is omitted, "x" represents the value 
whose arctangent is to be found,* in such a 
case, "x" may be real or complex, but if it 
is complex, it must not be equal to ±li. 

If w y" is specified, then the value 
whose arctangent is to be found is taken to 
be the expression x/y. In this case, both 
w x w and "y" must be real, and both cannot 
be equal to at the same time. 

Result : When "x" alone is specified, the 
value returned by ATAN depends on the mode 
of ff x. " If "x" is real, the returned value 
is the arctangent of "x, m expressed in 
radians, where: 

-pi/2<ATAN(x)<pi/2 

If "x H is complex, the arctangent function 
is multiple-valued, and hence only the 
principal value can be returned. The prin- 
cipal value of ATAN for a complex argument 
"x" is defined as follows: 

~i*ATANH(i*x) 

If both "x" and "y w are specified, the 
possible values returned by this function 
are defined as follows: 

1. If y>0, the value is arctangent (x/y) 
in radians. 

2. If x>0 and y=0, the value is ;pi/2) 
radians . 

3. If x>0 and y<0, the value is (pi+ arc- 
tangent (x/y)) radians. 

4. If x<0 and y=0, the value is (-pi/2) 
radians . 



5. If x<0 and y<0, the value is C-pi+ 
arctangent (x/y)) radians. 



ATAND Mathematical Built-in Function 

Definition : ATAND finds the arctangent of 
a given real value and returns the result, 
expressed in degrees, to the point of 
invocation. 

Reference : ATAND (xl,y)) 

Arguments : Arguments w x w and "y" ("y" may 
be omitted) must be real values. If "y" is 
omitted, "x" represents the value whose 
arctangent is to be found. If "y" is spe- 
cified, the value whose arctangent is to be 
found is represented by the expression x/y; 
in this case, both "x" and w y w cannot be 
equal to at the same time. 

Result: If w y w is not specified, the value 
returned by this function is simply the 
arctangent of "x/'expressed In degrees, 
where: 

-90<ATANDCx)<90 

If "y w is specified, the value returned 
by this function is ATAN (x,y), except that 
the value is expressed in degrees and not 
in radians (see "ATAN Mathematical Built-in 
Function" in this section) ; that is, the 
returned value is defined as: 

ATAND(x,y) = (180/pi) *ATAN (x, y ) 



ATANH Mathematical Built-in Function 

Definition : ATANH finds the inverse hyper- 
bolic tangent of a given value and returns 
the result to the point of invocation. 
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Reference ; ATANH (x) 

Argument : The value whose inverse hyper- 
bolic tangent is to be found is represented 
by w x." If w x w is real, the absolute value 
of "x" must not be greater than or equal to 
1; that is, for real n x," it is an error if 
ABS(x)>l. If r 



is complex, it roust not 



be equal to ±1. 



Result: If "x" is real, the value returned 
by this function is the inverse hyperbolic 
tangent of "x. w For complex "x," the 
inverse hyperbolic tangent is defined as 
follows ; 

(LOG((l+x)/(l-x)))/2 

COS Mathematical Built-in Function 

Definition : COS finds the cosine of a 
given value, which is expressed in radians, 
and returns the result to the point of 
invocation. 

Reference : COS (x) 

Argument: The value whose cosine is to be 
found is given by "x"; this value can be 
real or complex and must be expressed in 
radians. 

Result : The value returned by this func- 
tion is the cosine of "x. n For complex 
argument w x, w the cosine of "x" is defined 
below, where x = yi+iy2 : 

cos (x)=cos (y*) *cosh (y 2 ) - i*sin(y ± ) *sinh(y 2 ) 

COSD Mathematical Built-in Function 

Definition : COSD finds the cosine of a 
given real value, which Is expressed in 
degrees, and returns the result to the 
point of invocation. 

Reference : COSD (x> 

Argument : The value whose cosine is to be 
found is given by "x"; this value must be 
real and must be expressed in degrees. 

Result : The value returned by this func- 
tion is the cosine of n x. w 

COSH Mathematical Built-in Function 

Definition : COSH finds the hyperbolic 
cosine of a given value and returns the 
result to the point of invocation. 

Reference : COSH (x> 

Argument : The value whose hyperbolic 
cosine is to be found is given by "x." 

Result : The value returned by this func- 
tion is the hyperbolic cosine of "x." For 



complex argument M x," the hyperbolic cosine 
of w x" is defined below, where x = yi+iy 2 : 

cosh(x)=cosh(y 1 )*cos (y 2 ) +i*sinh (y*) *sin(y 2 ) 

ERF Mathematical Bu i lt-in Function 

Definition : ERF finds the error function 
cf a given real value and returns it to the 
point of invocation. 

Reference : ERF (x) 

Argument : The value for which the error 
function is to be found is represented by 
"x"; this value must be real. 

Result : The value returned by this func- 
tion is defined as follows: 

1— f X - t 2 

ERF(x)=-V~ : rr >'e dt 
ERFC Mathematical Built-in Function 

Definition : ERFC finds the complement of 
the error function (ERF) for a given real 
value and returns the result to the point 
of invocation. 

Reference : ERFC (x) 

Argument : The argument, "x f " represents 
the value whose error function complement 



is to be found; 



must be real. 



Result : The value returned by this func- 
tion is defined as follows: 

ERFCCx) = 1-ERFCx) 

EXP Mathematical Built-in Function 

Definition : EXP raises e (the base of the 
natural logarithm system) to a given power 
and returns the result to the point of 
invocation. 

Reference : EXP (x) 

Argument : The argument, "x, " specifies the 
power to which e is to be raised. 

Result : The value returned by this func- 
tion is e raised to the power of "x." 

LOG Mathematical Built-in Function 

Definition : LOG finds the natural 
logarithm (i.e., base e) of a given value 
and returns it to the point of invocation. 

Reference : LOG (x) 

Argument : The argument, "x," is the value 
whose natural logarithm is to be found. If 
"x" is real, it must not be less than or 
equal to 0; if "x M is complex, it must not 
be equal to 0+0i. 
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Result : The value returned by this func- 
tion is the natural logarithm of "x. w 
However, if "x" is complex, the function is 
multiple-valued; hence, only the principal 
value can be returned. The principal value 
has the form w = u±i*v, where v lies in the 
range : 

-pi<v<pi 

LQG1Q Mathematical Built-in Function 

Definition ; LOG 10 finds the common 
logarithm (i.e., base 10) of a given real 
value and returns it to the point of 
invocation. 

Reference : LOG10 (x) 

Argument : The argument, "x," represents 
the value whose common logarithm is to be 
found; this value must be real and it must 
not be less than or equal to 0. 

Result : The value returned by this func- 
tion is the common logarithm of "x. " 

LOG2 Mathematical Built-in Function 

Definition : LOG2 finds the binary (i.e., 
base 2) logarithm of a given real value and 
returns it to the point of invocation. 

Reference : LOG2 (x) 

Argument : The argument, "x," is the value 
whose binary logarithm is to be found; it 
must be real and it must not be less than 
or equal to 0. 

Result : The value returned to this func- 
tion is the binary logarithm of w x. n 

SIN Mathematical Built-in Function 

Definition : SIN finds the sine of a given 
value, which is expressed in radians, and 
returns it to the point of invocation. 

Reference : SIN (x) 

Argument : The argument, "x," is the value 
whose sine is to be found; it must be ex- 
pressed in radians. 

Result : The value returned by this func- 
tion is the sine of "x." For complex argu- 
ment "x," the sine of "x" is defined below, 
where x = y± + i*y 2 : 

sin(x)=sin(y a .)*coshCy 2 > + i*cos(y J .) *sinh(y 2 ) 

SIND Mathematical Built-in Function 

Definition : SIND finds the sine of a given 
real value, which is expressed in degrees, 
and returns the result to the point of 
invocation. 



Reference : SIND (x) 

Argument : The argument, "x, w is the value 
whose sine is to be found; "x" must be real 
and it must be expressed in degrees. 

Result : The value returned by this func- 
tion is the sine of "x. w 



SINH Mathematical Built-in Function 

Definition : SINH finds the hyperbolic sine 
of a given value and returns the result to 
the point of invocation. 

Reference : SINH (x) 

Argument : The argument, "x," is the value 
whose hyperbolic sine is to be found. 

Result: The value returned by this func- 
tion is the hyperbolic sine of "x." For 
complex argument "x, w the hyperbolic sine 
of w x w is defined below, where x = yj.+i*y 2 : 

sinh(x)=sinh(y ± )*cos (y 2 ) +i*cosh (y^) *sin(y 2 ) 

SQRT Mathematical Built-in Function 

Definition : SQRT finds the square root of 
a given value and returns it to the point 
of invocation. 

Reference : SQRT Cx) 

Argument : The argument, w x, w is the value 
whose square root is to be found. If "x n 
is real, it must not be less than 0. 

Result : If "x" is real, the value returned 
by this function is the positive square 
root of n x. w If "x" is complex, the square 
root function is multiple-valued; hence, 
only the principal value can be returned to 
the user. The principal value has the form 
w = u±i*v, where either u>0, or u=0 and 
v>0. 

TAN Mathematical Built-in Function 

Definition : TAN finds the tangent of a 
given value, which is expressed in radians, 
and returns it to the point 'of invocation. 

Reference : TAN Cx) 

Argument : The argument, "x," represents 
the value whose tangent is to be found; "x" 
irust be expressed in radians. 

Result : The value returned by this func- 
tion is the tangent of "x. " 

TAND Mathematical Built-in Function s 

Definition : TAND finds the tangent of a 
given real value which is expressed in 
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degrees, and returns the result to the 

point of invocation. 

Referen c e: TAMP (x) 

Argument : The argument, "x," represents 
the value whose tangent is to be found; "x" 
must be expressed in degrees. 

Result : The value returned by this func- 
tion is the tangent of "x." 

TANH Mathematical Built-in Function 

Defi nition: TANH finds the hyperbolic tan- 
gent of a given value and returns tne 
result to the point of invocation. 

Reference : TANH (x) 

A rgumen t: The argument, m x, n represents 
the value whose hyperbolic tangent is to be 
found. 

Resul t: The value returned by this func- 
tion is the hyperbolic tangent of "x. " 

Summar y of Mathematical Functions 

Figure 47 summarizes the mathematical 
built-in functions. In using it, the read- 
er should be aware of the following: 

i. A complex argument, *x, w is defined - 
as x = Yi+i*^- 

2. The value returned by each function is 
always in floating-point. 

3. The error conditions are those defined 
by the PL/I Language. Additional 
error conditions detected by the TSS/ 
360 PL/I compiler are described in the 
publication IBM System/360 Time Shar- 
ing System: PL/I Library Computation- 
al Subroutines , Form GC28-20*46. 

4. All arguments must be coded arithmetic 
and floating-point scale, or such that 
they can be converted to coded arith- 
metic and floating-point. 



the form of an element bit-string, to the 
point of invocation. The element bit- 
string indicates whether or not the corre- 
sponding bits of given array elements are 
all ones. 



Reference: 



ALL Cx) 



Argument : The argument, "x," is an array 
cf bit strings. If the elements are not 
tit strings, they are converted to bit 
strings. 

Resul t : The value returned by this func- 
tion is a bit string whose length is equal 
to the length of the longest element in w x w 
and whose tit values are determined by the 
following rule: 

If the ith bits of all of the elements 
in w x" exist and are 1, then the ith bit 
of the result is 1; otherwise, the ith 
bit of the result is 0. 



ANY Array Manipulation Function 

Definition : ANY tests the bits of a given 
tit-string array and returns the result, in 
the form of an element bit- string, to the 
point of invocation. The element bit- 
string indicates whether or not at least 
one of the corresponding bits of the given 
array elements is set to 1. 



Reference : 



ANY (x) 



Argument : The argument, w x f n is an array 
cf bit strings. If the elements are not 
bit strings, they are converted to bit 
strings. 

Result : The value returned by this func- 
tion is a tit string whose length is equal 
to the length of the longest element in "x" 
and whose bit values are determined by the 
following rule: 

If the ith tit of any element in "x" 
exists and is 1, then the ith bit of the 
result is 1; otherwise, the ith bit of 
the result is 0. 



ARRAY MANIPULATION BUILT-IN FUNCTIONS 

The built-in functions described here 
may be used for the manipulation of arrays. 
All of these functions require array argu- 
ments (which may be expressions) and return 
single element values. Note that since 
these functions return element values, a 
function reference to any of them is consi- 
dered an element expression. 

ALL Array Manipulation Function 

Definition : ALL tests all bits of a given 
bit-string array and returns the result, in 



DIM Array Manipulation Function 

Definition : DIM finds the current extent 
for a specified dimension of a given array 
and returns it to the point of invocation. 

Reference : DIM Cx,n) 



arguments : 



to be investigated; 



The argument "x" is the array 



is the dimension of 



'x, w the extent of which is to be found. 



If 



is not a binary integer, it is con- 



verted to a binary integer of default pre- 
cision. It is an error if m x m has less 
than "n" dimensions, if "n" is less than 
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or equal to 0, or if 

allocated* 



it; not currently 



Result : The value returned by this func- 
tion is a binary integer of default preci- 
sion, giving the current extent of the nth 
dimension of *x." 



HBOUND Array Manipulation Functio n 

Definition ; HBOUND finds the current upper 
bound for a specified dimension of a given 
array and returns it to the point of 
invocation. 

Reference : HBOUND (x,n) 

Arguments : The argument "x" is the array 
to be investigated; "n" is the dimension of 
"x" for which the upper bound is to be 
found. If *n* is not a binary integer, it 
is converted to a binary integer of default 
precision. It is an error if "x* has less 
than "n" dimensions, if "n" is less than or 
equal to 0, or if "x" is not currently 
allocated. 

Result : The value returned by this func- 
tion is a binary integer of default preci- 
sion giving the current upper tound for the 
nth dimension of "x." 

LBOUND Array Manipulation Function 

Definition : LBOUND finds the current lower 
bound for a specified dimension of a given 
array and returns it to the point of 
invocation. 

Reference : LBOUND (x f n) 

Arguments : The argument *x" is the array 
to be investigated; "n - is the dimension of 
m x m for which the lower bound is to be 
found. If •n" is not a binary integer, it 
is converted to a binary integer of default 
precision. It is an error if "x* has less 
than "n - dimensions, if "n* is less than or 
equal to 0, or if "x" is not currently 
allocated. 

Result : The value returned by this func- 
tion is a binary integer of default preci- 
sion giving the current lower bound of the 
nth dimension of w x. m 

POLY Array Manipulation Function 

Definition : POLY forms a polynomial from 
two given arguments and returns the result 
of the evaluation of that polynomial to the 
point of invocation. 

Reference : POLY (a,x) 

Arguments : Arguments "a" and "x" must be 
one- dimension arrays (vectors). They ar 
defined as follows: 



a (nun) 

xCp:q) 

where Cm:n> and Cp:q) represent the bounds 
of m a m and "x," respectively. 

Result: The value returned by this func- 
tion is defined as: 

n-rr j-1 

a(m>* ]T (a(m*j) * Tf x(p*i)> 
j=l i=0 

If (q-pX(n-m-l) , then x(p*i)=x(q> for 

Cp+i)>q. If m=n, then the result is aCm). 

If "x" is an element variable, it is 
interpreted as an array of one element, 

i.e., x(l>, and the result is then: 

n-.ro 
Yl a(ir»+j>*x**j 

PROD Array Manipulation Function 

Definition : PROD finds the product of all 
of the elements of a given array and 
returns that product to the point cf 
invocation. 



Reference: 



PROD (x) 



Ar gument : The argument, "x," should be an 
array of coded arithmetic floating-point 
elements. if it is not, each element is 
converted to coded arithmetic and floating- 
feint before being multiplied with the pre- 
vious product. 

Result : The value returned by this func- 
tion is the product of all of the elements 
in "x." The scale of the result is 
floating-point, while the base, mode, and 
precision arp those of the converted ele- 
ir'ents of "x." 

SUM Array Manipulation Function 

Definition : SUM finds the sum of all of 
the elements of a given array and returns 
that sum to the ^oint of invocation. 

Referenc e: SUM Cx) 

Argument : The argument, "x," should be an 
array of coded arithmetic floating-point 
elements. If it is not, each element is 
converted to coded arithmetic and floating- 
point before being summed with the previous 
total. 

Result : The value returned by this func- 
tion is the sum of all of the elements in 
•x. w The scale of the result is floating- 
point, while the base, mode, and precision 
are those of the converted elements of the 
argument . 
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CONDITION BUILT-IN FUNCTION: » 

The condition built-in functions allow 
the PL/ 1 user to investigate int e t rupt s 
that arise from enabled ON-condi tions. 
None of these functions requirt-s drqumentc. 
Each condition built-in function return;; 
the value described only when executed in 
an on-unit Cor a block activated directly 
or indirectly by an on-unit) that is 
entered as a result of an interruption 
caused by one ot the ON-oonditions tor 
which the function can be used. Such an 
on-unit can be one specific to the condi- 
tion, or if: can be for the ERROR or FINISH 
condition when these conditions are raised 
as standard system action. Lt a condition 
built-in function is used out of context, 
the value returned is as described for each 
function. 

The on-units in which each function can 

be used .-re given in the function 
def i nit: u. 



1. The use of the ONCHAR or ONSOURCE 
pseud< )- va r i utl.es . 

2. Changing the value of the field that 
caused the CONVERSION error. 

If ONCHAR is used out of context, a blank 
is ret urned - 

CNCQPIL Condi ti on Built-in Function 

Cef initicn; ONCODE can be used in any on- 
unit to determine the type of interruption 
that caused the on-unit to become active. 



Reference: 



ONCODE 



Result ; ONCODE returns a binary integer of 
default precision. This "code" defines the 
type of interruption that caused the entry 
into the currently active on-unit« The 
codes for the TSS/160 PL/I compiler are 
given in Part II, Section 8, w ON- 
Conditions." If ONCODE is used out of con- 
text, a value of is returned. 



DATAPiELD Condition Built-in Function 



CNCOUN1 Condition Built-in Function 



Definition : 



Whenever the NAME condition is 



raised, DATAFIELD may be used to extract 
the contents of the data field that ca used 
the convlit ion to be raised. It can be used 
only in an on-unit for the NAKL condition 
or in an ERROR or FINISH condition raised 
as a result of standard systeir action for 
the NAFE condition* 



Reference: DATAFIELD 



f unc- 



Result : The? value returned by this 
tion is a varying- length character string 
giving the contents of the data field that 
caused the NAWE condition to be raised. 
The maximum length of this string is 
defined by the TSS/360 PL/I compiler as 
255. If DATAFIELD is used out of context, 
a null string is returned. 



ONCHAR Condit ion Built-in Function 

Definition : Whenever the CONVERSION condi- 
tion is raised, ONCHAR may be used to 
extract the character that caused th** con- 
dition to be raised, it can be used only 
in an on-unit for the CONVERSION condition 
or in an on-unit for an ERROR or FINISH 
condition raised as standard system action 
for the CONVERSION condition. (ONCHAR can 
also be used as a pseudo-variable.) 



Reference: 



ONCHAR 



Result : The value returned by this func- 
tion is a character string of length I, 
containing the character that caused the 
CONVERSION condition to be raised. This 
character can be modified in the on-unit 
by: 



Def ini tio n: ONCOUNT can be used in any 
cn-unit entered due to the abnormal comple- 
tion of an I/O event to determine the num- 
ber of interruptions (including the current 
cne) that remain to be handled when a mul- 
tiple interruption has resulted from that 
abnormal completion. (Multiple interrup- 
tions are discussed in Part II , Section 8, 
"ON-Conditicns." ) 



Reference 



ONCOUNT 



R esult : ONCOUNT returns a binary value of 
default precision. If ONCOUNT is used in 
an on-unit enteied as part of a multiple 
interruption, this value specifies the cor- 
responding number of equivalent single 
Interruptions (including the current one) 
that remain to be handled; If ONCOUNT is 
used in any other case, the returned value 
is zero. 

ONFILE Condition Bui lt-ln Fu nction 

Definition: ONFILE determines the name of 
the file tor which an I/O or CONVERSION 
condition was raised and returns that name 
to the point ot invocation. This function 
can be used in the on-unit for any I/O or 
CONVERSION condition; it also can be used 
in an on-unit for an ERROR or FINISH condi- 
tion raised as standard system action for 
an I/O or CONVERSION condition. 

Refe rence: ONFILE 

Res ult : The value returned by this func- 
tion is a varying- length character string, 
of 31- character maximum length, consisting 
c f the name of the file for which an I/O or 
CONVERSION condition was raised. 
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In the case of a CONVERSION condition, if 
that condition is not associated with a 
file, the returned value is the null 
string. 

ONKEY Condition Built-in Function 

Definition ; ONKEY extracts the value of 
the key for the record that caused an I/O 
condition to be raised. This function can 
be used in the on-unit for an I/O condition 
or a CONVERSION condition; it can also be 
used in an on-unit for an ERROR or FINISH 
condition raised as standard system action 
for one of the above conditions. 

Reference s ONKEY 

Result ; The value returned by this func- 
tion is a varying- length character string 
giving the value of the key for the record 
that caused an input/output condition to be 
raised. If the interruption is not asso- 
ciated with a keyed record, or if the PEND- 
ING condition is raised, the returned value 
is the null string. 

QNLQC Condition Built-in Function 

Definition : Whenever an ON- condition is 
raised, ONLOC may be used in the on-unit 
for that condition to determine the entry 
point to the procedure in which that condi- 
tion was raised. ONLOC may be used in any 
on-unit. 

Reference ; ONLOC 

Result : The value returned by this func- 
tion is a varying- length character string 
giving the name of the entry point to the 
procedure in which the ON-condition was 
raised. If ONLOC is used out of contejrt, a 
null string is returned. 

ONSOURCE Condition Built-in Function 

Definition : Whenever the CONVERSION condi- 
tion is raised, ONSOURCE may be used to 
extract the contents of the field that was 
being processed when the condition was 
raised. This function can be used in the 
on-unit for a CONVERSION condition or in an 
on-unit for an ERROR or FINISH condition 
raised as standard system action for a CON- 
VERSION condition. CONSOURCE can also be 
used as a pseudo- variable. > 

Reference : ONSOURCE 

Result : The value returned by this func- 
tion is a varying- length character string 
(maximum length is 255 for the compiler) 
giving the contents of the field being pro- 
cessed when CONVERSION was raised. This 
string may be modified in the ^n-unit by: 

1. Use of the ONCHAR or ONSOURCE 
pseudo- variables . 



2. Changing the value of the field which 
caused the CONVERSION error* 

If ONSOURCE is used out of context, a 

null string is returned. 



BASED STORAGE BUILT- IN FUNCTI ONS 

The based storage built-in functions 
generally return special values to program 
control variables concerned in the use of 
based storage and list processing* Only 
ADDR requires an argument . 

A DDR Bas ed Storage Built-in Function 

Definition : ADDR finds the location at 
which a given variable has been allocated 
and returns a pointer value to the point of 

invocation. The pointer value identifies 
the location at which the variable has been 
allocated* 

Reference : ADDR Cx) 

Argument : The argument f B x," is the vari- 
able whose location is to be found* It can 
be any variable that represents an element § 
an array, a structure, an area, an element 
of an array, a minor structure, or an ele- 
ment of a structure. It can be of any data 
type and storage class. For the TSS/360 
PL/I compiler, the variable should not be a 
bit-string variable forming part of an 
unaligned array or structure. 

Result : ADDR returns a pointer value iden- 
tifying the location at which w x" has been 
allocated. If "x* is a parameter, the 
returned value identifies the corresponding 
argument (dummy or otherwise)* If "x" is a 
based variable, the returned value is 
determined from the pointer variable 
declared with m x m ; if this pointer variable 
has not been set, the value returned by 
ADDR is undefined. If *x* is an unallo- 
cated controlled variable, a null pointer 
value is returned. 

EMPTY Ba sed Storage Biiilt-ia ,, .Function 

Definition : EMPTY clears an area of 

storage defined by an area variable , by 
effectively freeing ail the allocations 
contained within the area. The area can 
then be used for a new set of allocations. 

Reference ; EMPTY 

Arguments ; None 

Result : EMPTY returns an area of xero 
size, containing no allocations, to the 
point of invocation. When this value is 
assigned to an area variable, all the allo- 
cations contained within the area are 
freed • 
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Notes The value of the EMPTY built-in 
function is automatically assigned to all 
area variables when they are allocated. 

NULL Based Storage Built-in Function 

Definition : NULL returns a null pointer 
value (that is, a pointer value that cannot 
identify any allocation) so as to indicate 
that a pointer variable does not currently 
identify an allocation. 



Reference: 



NULL 



Arguments : None 

Result : The value returned by this func- 
tion is a null pointer value. This value 
cannot be converted to offset type. 

NULLO Based Storage Built-in Function 

Definition ; NULLO returns a null offset 
value (that is f an offset value that cannot 
identify any relative location of a based 
variable allocation) so as to indicate that 
an offset variable does not currently iden- 
tify an allocation. 

References NULLO 



Arguments : 



Results 



None 



The value returned by this func- 
tion is a null offset value. This value 
cannot be converted to pointer type. 



active or inactive. An array argument 
causes an array value to be returned. 

Result : The value returned by this func- 
tion is 'O'B if the event is incomplete, 

*l f B if the event is complete. 

STATUS Multitasking Built-in Function 

Definition : STATUS determines the status 
value of a given event variable. (STATUS 
can also be used as a pseudo- variable. ) 

Reference ; STATUS (event- name) 

Argument ; The argument r "event-name", can 
be an event element or an event array. It 
represents the event (or events) whose sta- 
tus value is to be determined. The event 
can be associated with completion of a 
task, or with completion of an input/ out put 
operation, or it can be user-defined. It 
can be active or inactive. An array argu- 
ment causes an array value to be returned. 

Result: The value returned by this func- 
tion is a fixed binary value of default 
precision ((15,0) for the TSS/360 PL/I com- 
piler). It is zero if the event is normal, 
or nonzero if abnormal. The nonzero value 
is set to 1 as a result of the completion 
of the task, or input/output operation, 
with which the event variable has been 
associated by the event option. If the 
nonzero value is user defined it can be set 
to any value the user selects. 



MULTITASKING BUILT-IN FUNCTIONS 

The multitasking built-in .functions are 
designed to be used during multitasking and 
during asynchronous I/O operations. The 
summaries below describe the intended, 
rather than actual, workings of the func- 
tions. In TSS/360 only the COMPLETION and 
STATUS functions can be executed success- 
fully, and these only to investigate the 
current state of execution of an I/O opera- 
tion. They both reguire arguments. 

COMPLETION Multitasking Built-in Function 

Definition : COMPLETION determines the com- 
pletion value of a given event variable. 
(COMPLETION can also be used as a 
pseudo- variable. ) 

Reference : COMPLETION (event- name) 

Argument : The argument, "event- name", can 
be an event element or an event array. It 
represents the event (or events) whose com- 
pletion value is to be determined. The 
event can be associated with completion of 
a task, or with completion of an I/O opera- 
tion, or it can be user-defined. It can be 



MISCELLANEOUS BUILT-IN FUNCTIONS 

The functions described in this section 
have little in common with each other and 
with the other categories of built-in func- 
tions. Some reguire arguments and others 
do not. Those that do not reguire argu- 
ments will be so identified. 

ALLOCATION Built-in Function 

Definition : ALLOCATION determines whether 
or not storage is allocated for a given ' 
controlled variable and returns an appro- 
priate indication to the point of 
invocation. 

Reference : ALLOCATION (x) 

Argument : The argument, "x," must be an 
unsubscripted array name, a major structure 
name, or an element variable name, and it 
must have the COOTROLLED attribute. 

Result : The value returned by this func- 
tion is defined as follows: if storage has 
been allocated for m x g m the returned value 
is '1 8 B (provided that the allocation is 
known to the task executing the function) ; 
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if storage has not been allocated for "x, 1 
the returned value is 'O'B. 



COUNT Built-in Function 

Definition: COUNT determines the number of 
data items that were transmitted during the 
last GET or PUT operation on a given file 
and returns the result to the point of 
invocation. 

Reference : COUNT (file-name) 

Argument : The argument, "file name," 
represents the file to be investigated. 
This file must have the STREAK attribute. 

Result : The value returned by this func- 
tion is a binary fixed-point integer of 
default precision specifying the number of 
element data items that were transmitted 
during the last GET or PUT operation on 
"file name." Note that if an on-unit or 
procedure is entered during a GET or PUT 
operation, and within that on-unit or pro- 
cedure a GET or PUT is executed for the 
same file, the value of COUNT is reset for 
the new operation and is not restored when 
the original GET or PUT is continued. 



DATE Built-in Function 



Definition: 



DATE returns the current date 



to the point of invocation. 
Reference : DATE 

Arguments : Non e 

Result : The value returned by this func- 
tion is a character string of length six, 
in the form yymmdd , where: 

yy is the current year 

mm is the current month 

dd is the current day 

Example : If the current date is March 4, 
1969, execution of the statement 

X = DATE; 

will cause the character string '690304' to 
be returned to the point of invocation. 

LINENQ Built-in Function 

Definition : LINENO finds the current line 
number for a file having the PRINT attri- 
bute and returns that number to the point 
of invocation. 

Reference: LINENO (file-name) 



Arguirent : The argument, "file name," must 

be the name of a file having the PRINT 

attribute. 

Result : The value returned by this func- 
tion is a binary fixed-point integer of 

default precision specifying the current 
line number of "file name*" 

TIM E Built-in Function 

Definition : TIME returns the current time 
to the point of invocation. 

Reference : TIME 

Arguir ents : None 

Re sult : The value returned by this func- 
tion is a character string of length nine, 
in the form hhromssttt , where: 

hh is the current hour of the day 

mm is the number of minutes 

ss is the number of seconds 

ttt is the number of milliseconds in 
machine-dependent increments 

Example : If the current time is *4 P.M., 23 
minutes, 19 seconds, and 80 milliseconds, a 
reference to the TIME function, for some 
computers, will return the character string 
'162319080' to the point of invocation. 



PS EU CO-VARIABLES 

In general, pseudo-variables are certain 
built-in functions that can appear wherever 
other variables can appear in order to 
receive values. In short, they are built- 
in functions used as receiving fields. For 
example, a pseudo-variable may appear on 
the left of the equal sign in an assignment 
or DO statement; it may appear in the data 
list of a GET statement; it may appear as 
the string name in the STRING option of a 
PUT statement. 

Since all pseudo-variables have built-in 
function counterparts, only a short 
description of each pseudo-variable is 
given here; the discussion of the corre- 
sponding built-in function should be con- 
sulted for the details. Note that pseudo- 
variables cannot be nested; for example, 
the following statement is invalid: 

UNSPECCSUBSTR(A,1, 2))= f 00'B; 

COMPLETION Pseudo-variable 



Reference: 



COMPLETION (event-name) 
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Descri p tion : The 
be inactive and i 
COMPLETION built- 
received by this 
string of length 
completion value 
val ue of 'O'B spe 
associated with t 
in comp lete; a va .1 
the event is conip 
take place during 
pseudo-varia ble. 



named event variable must 
s as described for the 
in function- The value 
pseudo-variable is a bit- 
1. This value sets the 
of the event variable. A 
cities that the event 
he "event variable" is 
ue of ' l'B specifies that 
lete- No interruption can 

assignment to the 



COMPLEX P seudc-variable 

Reference: C OMPLEX (a,b) 

Description: Only complex values can be 
assigned to this pseudo-variable. The real 
part of the complex value is assigned to 
the variable "a"; the imaginary part is 
assigned to the variable "b." If either 
M a" and "b n is an array, both must be 
arrays of identical bounds. 

I MAG P seudo- variable 

Refe rence : I MAG C c ) 

Descript ion: Heal or complex values may be 
assigned to this pseudo- variable. The real 
value or the real part of the complex value 
is assigned to the imaginary part of the 
complex variable "c, " which may be an ele- 
ment variable or an array variable. 

ONCHAR Pseudo- variable 



Reference: 



ONCHAR 



Description : ONCHAR can be used in the 
on-unit for a CONVERSION condition or in 
the on-unit for an ERROR or FINISH condi- 
tion raised as standard system action for a 
CONVERSION condition; it can also be used 
in a block directly or indirectly activated 
by such an on-unit. If ONCHAR is used in 
some other context, it is an error. 

The expression being assigned to ONCHAR 
is evaluated, converted to a character 
string of length 1, and assigned to the 
character that caused the error. The new 
character will displace the current value 
of the ONCHAR built-in function, and will 
be used when the conversion is re- 
attempted, upon the resumption of execution 
at the point of interruption. 

ONSOURCE Pseudo-variable 

Reference : ONSOURCE 

Description : ONSOURCE can be used in the 
on-unit for a CONVERSION condition or in an 
on-unit for an ERROR or FINISH condition 
raised as standard system action for a CON- 
VERSION condition? it can also be used in a 



block directly or indirectly activated by 
such an on-unit. If ONSOURCE is used in 
some other context, it is an error. 

The expression being assigned to 
ONSOURCE is evaluated, converted to a char- 
acter string, and assigned to the string 
that caused the CONVERSION condition to be 
raised. The string will be padded with 
blanks, if necessary, to match the length 
cf the string that caused the error. This 
new string displaces the current value of 
the ONSOURCE built-in function and will be 
used when the. conversion is re-attempted, 
upon the resumption of execution at the 
point of interruption. 

REAL Pseudo-variable 

R eference : REAL (c) 

Description : Real or complex values may be 
assigned to this pseudo-variable. The real 
value or the real part of the complex value 
is assigned to the real part of the complex 
variable "c," which may be an element vari- 
able or an array variable. 

STATUS Pseudo-variable 

R eference : STATUS (event -name) 

Description: The named event variable can 
be active or inactive, and is as described 
for the STATUS built-in function. The 
value received by this pseudo-variable is a 
fixed point binary value of default preci- 
sion ((15,0) for the TSS/360 PL/I compil- 
er). No interruption can occur during 
assignment to the pseudo-variable. 

STRING Pseudo-variable 

Reference : STRING (x) 

Description : The argument B x w is an ele- 
ment, array, or structure variable, com- 
posed either entirely of character strings 
and/or numeric character data, or entirely 
cf bit strings. The variable may be 
aligned or unaligned. 

Note: For the TSS/360 compiler, the argu- 
ment to a STRING pseudo-variable cannot be 
a cross section of an array. 

The value being assigned must be an ele- 
ment expression and is converted, if neces- 
sary, to bit-string or character-string 
type, depending on the characteristics of 
the argument " x w . It is then assigned 
piece by piece to the elements of "x n , 
using the normal rules of string assign- 
ment, until either all of the elements of 
the aggregate have been assigned to, or no 
portion of the assigned string remains. In 
the latter case, the normal string assign- 
ment rules apply to the remainder of the 
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aggregate, i.e., varying strings are given 
a zero length, and non-varying strings are 
filled with blanks. (The length of each 
assigned piece is determined by the length 
of the corresponding element of the argu- 
ment; the normal rules for string assign- 
ment apply if the last piece is too short.) 

STRING pseudo-variable can only be used 
in an assignment statement and a DO state- 
ment. It cannot be used in options such as 
REPLY and KEYTO. 

SUBSTR Pseudo-variable 

R eference : SUBSTR ( string, i t , jl ) 

Lescription : The value being assigned to 
SUBSTR is assigned to the substring of the 
character- or bit-string variable "string, 1 
as defined for the built-in function SUB- 
STR. If "string" is an array, i and/or j 
may be arrays, in which case they must have 



identical bounds. The remainder of 
"string" remains unchanged. The SUBSTR 
pseudo-variable cannot be applied to a num- 
eric picture. 



UNSPEC Pseudo-variable 



Reference: UNSPEC (v) 
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SECTION 8: ON- CONDITIONS 



The ON- conditions are those exceptional 

conditions that can be specified in PL/I by 
means of an ON statement. If a condition 
is enabled, the occurrence of the condition 
will result in an interruption- The inter- 
ruption,, in turn, will result in the execu- 
tion of the current action specification 
for that condition. If an ON statement for 
that condition is not in effect, the cur- 
rent eiction specification is the standard 
system action for that condition. If an ON 
statement for that condition is in effect, 
the current action specification is either 
SYSTEM, in which case the standard system 
action for that condition is taken, or an 
on-unit, in which case the user has sup- 
plied his own action to be taken for that 
condition. 

It a condition is not enabled (i.e., if 

t is disabled), and the condition occurs, 
j^n interruption will net take place, and 
errors may result. 

Seine conditions are always enabled 
unless they have been explicitly disabled 

by condition prefixes; others are always 
disabled unless they have been explicitly 
enabled by condition prefixes; and still 
others are always enabled and cannot be 

disabled. 

Those conditions that are always enabled 
unless they have been explicitly disabled 
by condition prefixes are: 



Section 13, "Exceptional Condition Handling 

and Program Checkout.") 

Conversely, those conditions that are 
always disabled unless they have been 
enabled by a condition prefix are: 

SIZE 

SUBSCRIPTRANGE 
STRINGRANGE 
CHECK 

The appearance of one of these four in a 
condition prefix renders the condition 
enabled throughout the scope of the prefix; 
the condition remains disabled outside this 
scope. Further, a condition prefix speci- 
fying NOSIZE, NOSUBSCRIPTRANGE, NOSTRING- 
RANGE, or NOCHECK will disable the corre- 
sponding condition throughout the scope of 
that prefix. 

All other conditions are always enabled 
and remain so for the duration of the pro- 
gram. These conditions are; 

AREA 

CONDITION 

ENDFILE 

ENDPAGE 

ERROR 

FINISH 

KEY 

NAME 

RECORD 

TRANSMIT 

UNEEFINEDFILE 



CONVERSION 
FIXEDOVERFLOW 

OVERFLOW 

UNDERFLOW 

ZERODIVIDE 

Each of the above conditions can be dis- 
abled by a condition prefix specifying the 
condition name preceded by NO without 
intervening blanks. Thus, one of the fol- 
lowing names in a condition prefix will 
disable the respective condition: 

NOCONVERSION 
NOFIX EDOVERFLOW 
NOOVERFLOW 
NOUNDERFLOW 
NOZERODIVIDE 

Such a condition prefix renders the corre- 
sponding condition disabled throughout the 
scope of the prefix; the condition remains 
enabled outside this scope. (Scope of a 
condition prefix is discussed in Pert I, 



Condition Codes (QN-Codes) 

The ONCODE built-in function may be used 
by the user in any on- unit to determine the 
nature of the error or condition that 
caused entry into that on-unit. The codes 
corresponding to the conditions and errors 
checked for by the TSS/360 PL/I coirpiler 
are given below: 



Code 

3 

'4 



9 
10 
20 
21 

22 

23 



C c^dition/Erro r 

OPCODE function used out of context 

Source program error 

FINISH C normal termination, or sig- 
naled by STOP or EXIT) 

ERROR (signaled) 

NAME 

RECORD (signaled) 

RECORD (record variable smaller than 
record size) 

RECORD (record variable larger than 
record size) 

RECORD (attempt to write zero length 
record) 
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24 

40 
41 
42 
50 
51 
52 
53 
54 
55 
56 

57 

70 
80 
81 
82 

83 

84 

90 
300 
310 
320 
330 
340 
341 
350 
360 

361 
362 
500 
510 
511 
520 
600 
601 
602 
603 
604 

605 

606 
607 

608 

609 
610 

611 

612 

613 

614 

615 

616 



(blocksize not 



RECORD (zero length record has been 
read) 

TRANSMIT (signaled) 

TRANSMIT (output) 

TRANSMIT (input) 

KEY (signaled) 

KEY (keyed record not found) 

KEY (attempt to add duplicate key) 

KEY (key sequence error) 

KEY (key conversion error) 

KEY (key specification error) 

KEY (keyed relative record/track 
outside data set limit) 

KEY (no space available to add keyed 
record) 

ENDFILE 

UNDEFINEDFILE (signaled) 

UNDEFINEDFILE (attribute conflict) 

UNDEFINEDFILE (access method not 
supported) 

UNDEFINEDFILE 
specified) 

UNDEFINEDFILE (file cannot be 
opened, no DDEF command) 

END PAGE 

OVERFLOW 

FIXEDOVERFLOW 

ZERQDIVIDE 

UNDERFLOW 

SIZE (normal) 

SIZE (I/O) 

STRINGRANGE 

AREA (raised by based variable 

allocation) 

AREA (raised by area assignment) 

AREA (signaled) 

CONDITION 

CHECK (LABEL) 

CHECK (variable) 

SUBSCRIPTRANGE 

CONVERSION (internal) (signaled) 

CONVERSION (I/O) 

CONVERSION (transmit) 

CONVERSION (error in F-format input) 

CONVERSION (error in F-format input) 
(I/O) 

CONVERSION (error in F-format input) 
(transmit) 

CONVERSION (error in E-format input) 

CONVERSION (error in E-format input) 
(I/O) 

CONVERSION (error in E-format input) 
(transmit) 

CONVERSION (error in B- format input) 

CONVERSION (error in B-format input) 
(I/O) 

CONVERSION (error in B-format input) 
(transmit) 

CONVERSION (character-string to 
arithmetic) 

CONVERSION (character-string to ari- 
thmetic) (I/O) 

CONVERSION (character-string to ari- 
thmetic) (transmit) 

CONVERSION (character-string to 
bit-string) 

CONVERSION (character-string to bit- 
string) (I/O) 



617 CONVERSION (character-string to bit- 

string) (transmit) 

618 CONVERSION (character to picture) 

619 CONVERSION (character to picture) 

(I/O) 

6 20 CONVERSION (character to picture) 
(transmit) 

6 21 CONVERSION (P- format input — 
decimal) 

6 22 CONVERSION (P- format input — deci- 
mal) (I/O) 

623 CONVERSION (P-format input -- deci- 
mal) (transmit) 

6 24 CONVERSION (P- format input -- 
character) 

6 25 CONVERSION ( P- format input — 
character) (I/O) 

6 26 CONVERSION (P-format input -~ 
character) (transmit) 

627 CONVERSION (P-format input -- 

sterling) 

628 CONVERSION (P-format input — ster- 

ling) (I/O) 

629 CONVERSION (P-format input -- ster- 

ling) (transmit) 

1000 Attempt to read output file 

1001 Attempt to write input file 

1002 GET/PUT string length error 

100 3 Unacceptable output transmission 
error 

1004 Print option on non-PRINT file 

1005 Message length for DISPLAY state- 

ments is zero 

1006 Illegal array data item for data- 

directed input 

1007 REWRITE not immediately preceded by 

READ 

1008 GET STRING — unrecognizable data 

name 

1009 Unsupported file operation 

1010 File type not supported 

1011 Inexplicable I/O error 

1012 Outstanding read for update exists 

1013 No completed read exists -- incor- 

rect NCP value 

1014 Too many incomplete I/O operations 

1015 Event variable already in use 

1016 Implicit open failures — cannot 

proceed 

1017 Attempt to rewrite out of sequence 

1018 ERROR condition raised when end of 
file encountered unexpectedly in 
list-directed or data-directed 
input, or when field width in format 
list of edit- directed input would 
take scan beyond end of file. 

1019 Attempt to close file not opened in 
! current task. 

1500 Short SQRT error 

1501 Long SQRT error 
150 4 Short LOG error 
15 05 Long LOG error 

1506 Short SIN error 

1507 Long SIN error 

1508 Short TAN error 

1509 Long TAN error 

1510 Short ARCTAN error 

1511 Long ARCTAN error 
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1512 


1513 


1514 


1515 


1550 


1551 


1552 


15 53 


1554 


L555 


j 556 


1557 


15 5« 


15 5^ 


2000 


2 001 


J000 


3001 


300 2 


30 3 


300i4 


300 5 


300b 


379 8 



J799 

3800 

3801 

3900 

3901 
3902 
39 3 

3904 

3905 

3906 

3907 
3908 

8091 
8092 
8093 
8094 
8095 
8096 
8097 
9000 

9001 
9002 

9003 



Short GINH error 

Long SINK error 

Short ARCTANH error 

Long ARCTANH error 

Invalid exponent in short float 

integer exponentiation 
Invalid exponent in long float 

integer exponentiation 
Invalid exponent in short float gen- 
eral exponentiation 
Invalid exponent In long float gen- 
eral exponentiation 
Invalid exponent in complex short 

float integer exponentiation 
Invalid exponent in complex long 

float integer exponentiation 
Invalid exponent in complex short 

float general exponentiation 
invalid exponent in complex long 

float general exponentiation 
Invalid argument in short float com- 
plex ARCTAN or ARCTANH 
Invalid argument in long float com- 
plex AKCTAN or ARCTANH 
Unacceptable DEIAY statement 
Unacceptable TIKE statement 
S- format conversion error 
F-format conversion error 
A- format conversion error 
d- format conversion error 
A- format input error 
B- format input error 
Picture character-string error 
ONSOURCE or ONCHAR pseudo- variables 

used out of context 
Improper return from CONVERSION 

on- u nit 
Structure length > 16**6 bytes 
Virtual origin of array > 16**6 or 

<-16**6 
Attempt to wait on inactive and 

incomplete event 
Task variable already active 
Event already being waited for 
Wait on more than 2 55 incomplete 
events 

Active event variable as argument to 
COMPLETION pseudo-variafcle 
Invalid task variable as argument to 
PRIORITY pseudo-variatle 
Event variable active in assignment 
statement 

Event variable already active 
Attempt to wait for I/O event in 
wrong task 
Invalid operation 
Privileged operation 
EXECUTE statement executed 
Protection violation 
Addressing interruption 
Specification interruption 
Data interruption 
Too many active on-units and entry 

parameter procedures 
No invocation count 
Invalid free storage (main 

procedure) 
Invalid free VDA 



Multiple Interruptions 

A m ultiple interruption can occur only 
for an input/output operation that has been 
associated with an event variable. It 
occurs during the execution of the WAIT 
statement naming that event variable, if 
the event has been completed abnormally 
(i.e., if one or more conditions occurred 
during the operation). Since conditions 
for an input/output event are raised at the 
execution of the WAIT for that event, the 
interruptions for these conditions also 
occur at this time. It is possible for 
more than one interruption to occur for an 
input/output event. The aggregate of 
interruptions for an input/output event is 
called a multiple interruption. 

When an input/output event is completed 
abnormally, the order in which the condi- 
tions are raised, and therefore, the order 
in which the interruptions for these condi- 
tions occur, is implementation defined. If 
the on-unit for such a condition ends 
abnormally, then all unprocessed renditions 
(i.e., remaining interruptions of the mul- 
tiple interruption) are ignored; if an on- 
unit ends normally, the next condition is 
processed. If an on-unit has not been 
established for such a condition or if SYS- 
TEM is in effect, the next condition out- 
standing will be processed only if the 
standard system action is to comment and 
continue; if the standard system action is 
otherwise, all remaining interruptions in 
the multiple interruption will be ignored. 



Note: 



If the UNDEFINEDFILE condition is 



raised by an attempt at implicit opening, 
caused by a statement associated with an 
event variable, the condition is raised 
immediately, and the interruption will 
cccur even before the WAIT statement is 
executed. 



SECTION ORGANIZATI ON 

This section presents each condition in 
its logical grouping, and in alphabetical 
order within that grouping. In general, 
the following information is given for each 
condition: 

*• Ge neral format — given only when it 
consists of more than the condition 
name. 

2. Description -- a discussion of the 

condition, including the circumstances 
under which the condition can be 
raised. Note that an enabled condi- 
tion can always be raised by a SIGNAL 
statement; this fact is not included 
in the descriptions. 
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3 * Result — the result of the operation 
that caused the condition to occur. 
This applies when the condition is 
disabled as well as when it is 
enabled- In some cases, the result is 
not definedf that is f it cannot be 
predicted. This is stated wherever 
applicable. 



Standard system action — the action 
taken by the system when an interrup- 
tion occurs and the user has not spec- 
ified an on-unit to handle that 
interruption. 



4. List processing condition - — the AREA 
condition , which is associated with 
area usage, 

5. System action conditions -- those con- 
ditions that, provide facilities to 
extend the standard system action that 
is taken after the occurrence of a 
condition or at the completion of a 
program. They are: 

ERROR 
FINISH 

6. User-named condition — the CONDITION 
condition. 



5. Status 



— an indication of 

enabled/disabled status of 



the 

the condi- 
tion at the start of the program, and 
how the condition may be disabled (if 
possible) or enabled, 

6. Normal return — the point to which 

control is returned as a result of the 
normal termination of the on- unit • A 
GO TO statement that transfers control 
out of an on-unit is an abnormal on- 
unit termination. Note that if a con- 
dition has been raised by the SIGNAL 
statement , the normal return is always 
to the statement immediately following 
SIGNAL. 

The conditions are grouped as follows s 

1. Computational conditions — those con- 
ditions associated with data handling, 

expression evaluation, and computa- 
tion* They ares 

CONVERSION 

FIXEDOVERFLOW 

OVERFLOW 

SIZE 

UNDERFLOW 

ZERODIVIDE 

2- Input/output conditions -- those con- 
ditions associated with data transmis- 
sion. They ares 

ENDFILE 

ENDPAGE 

KEY 

NAME 

PENDING 

RECORD 

TRANSMIT 

UNDEFINEDFILE 

3- Program- checkout conditions — those 
conditions that facilitate the debug- 
ging of a program. They ares 

CHECK 

SUBSCR1PTRANGE 

STRINGRANGE 



COMPUTAT ION AL_tt EDITIONS 

The CONV ERSION Conn it ion 

Description s The CONVERSION condition 
occurs whenever an illegal conversion is 
attempted on character-string data* This 
attempt may be made internally or during an 
input/output operation. For example, the 
condition occurs when a character other 
than or 1 exists in a character string 
being converted to a bit string; other 
examples are when a character string being 
converted to a numeric character field con- 
tains characters not permitted by the PIC- 
TURE specification or when a string being 
converted to coded arithmetic data does not 
contain the character representation of an 
arithmetic constant. 

All conversions of character- string data 
are carried out character- by-character in a 

left -to- right sequence and the condition 
occurs for each invalid character. When an 
invalid character is encountered, an inter- 
ruption occurs (if, of course, that CONVER- 
SION has not been disabled) and the current 
action specification for the condition is 
executed. If the action specification is 
an on-unit , the invalid character can be 
corrected within the unit by using the 
ONSO0RCE or ONCHAR pseudo- variables. On 
return from on-unit, the conversion of the 
string is retried frojn the beginning. For 
the compiler, if the illegal character has 
not been corrected, a message is printed 
and the ERROR condition is raised. 

Note : If conversion of 3 character-string 
of significant length greater than 16 to an 
arithmetic field is attempted, and a conv- 
ersion on-unit is enabled in which the 
ONCHAR built-in function is used to replace 
an invalid character with a Kuoieric 
character , the following happens: 

The CONVERSION condition is raised due to 
the excessive string length, and the repla- 
cement character does not alleviate this 
condition. Therefore, a loop occurs 
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(between the conversion module and the 
on-unit- 

Result : When CONVERSION occurs, the con- 
tents of the entire result field are 
undefined. 

Standard System Action ; In the absence of 
an on- unit , the system prints a message and 
raises the ERROR condition. 

Status ; CONVERSION is enabled throughout 
the program, except within the scope of a 
condition prefix specifying NOCONVERSION. 

Normal Return s Upon the normal termination 
of the on-unit for this condition, control 
returns to the beginning of the string and 

the conversion is retried. 

The FIXEDOVERFLOW Condition 

Description : The FIXEDOVERFLOW condition 
occurs when the length of the result of a 
fixed- point arithmetic operation exceeds 
the maximum length allowed by the implemen- 
tation. For System/360 implementations, 
this maximum is 15 for decimal fixed-point 
values and 31 for binary fixed- point 
values. 

Result ; The result of the invalid fixed- 
point operation is undefined. 

Standard System Action : In the absence of 
an on-unit, the system prints a message and 
raises the ERROR condition. 

Status : FIXEDOVERFLOW is enabled through- 
out the program, except within the scope of 

a condition prefix that specifies 

NOF1XEDOVERFLOW . 

Normal Return : Upon normal termination of 
the on-unit for this condition, control 
returns to the point immediately following 
the point of interruption. 

The OVERFLOW Condition 

Description : The OVERFLOW condition occurs 
when the magnitude of a floating-point 
number exceeds the permitted maximum. (For 
System/360 implementations, the magnitude 
of a floating-point number or intermediate 
result must not be greater than approxi- 
mately 10" or 2 aM .) 

Result ; The value of such an illegal 
floating-point number is undefined. 

Standard System Action : In the absence of 

an on-unit, the system prints a message and 
raises the ERROR condition. 

Status : OVERFLOW is enabled throughout the 
program, except within the scope of a con- 
dition prefix specifying NOOVERFLOW,. 



Normal Return : Upon normal termination of 
the on-unit for this condition, control 
returns to the point immediately following 
the point of interruption. 

The SIZE Condition 

Description s The SIZE condition occurs 
only when high-order (i.e.* leftmost) sig- 
nificant binary or decimal digits are lost 
in an assignment to a variable or a tem- 
porary or in an I/O operation. This loss 
may result from a conversion involving dif- 
ferent data types, different bases, dif- 
ferent scales, or different precisions. 

The SIZE condition differs from the 
FIXEDOVERFLOW condition in an important 
sense, i.e., FIXEDOVERFLOW occurs when the 
size of a calculated fixed-point value 
exceeds the maximum allowed by the imple- 
mentation (see the description of the 
FIXEDOVERFLOW condition), whereas SIZE is 
raised when the size of the value being 
assigned to a data item exceeds the 
declared (or default) size of the data 
item. SIZE can be raised on assignment of 
a value regardless of whether or not FIXED- 
OVERFLOW was raised in the calculation of 
that value. 

The declared size is not necessarily the 
actual precision with which the item is 
held in storage; however, the limit for 
SIZE is the declared or default size, not 
the actual size in storage. For example, 
with the TSS/360 PL/I compiler, a fixed 
binary item of precision (20) will occupy a 
fullword in storage, but SIZE is raised if 
a value whose size exceeds FIXED BINARY (20) 
is assigned to it. 

Result : The contents of the data item 
receiving the wrong-sized value are 
undefined. 

Standard System Action : In the absence of 
an on-unit, the system prints a message and 
raises the ERROR condition. 

Status: SIZE is disabled within the scope 
of a NOSIZE condition prefix and elsewhere 
throughout the program, except within the 
scope of a condition prefix specifyincr 
SIZE. 

Normal Return : Upon normal termination of 
the on-unit for this condition, control 
returns to the point immediately following 

the point of interruption. 

The UNDERFLOW Condition 

Description : The UNDERFLOW condition 
occurs when the magnitude of a floating- 
point number is smaller than the permitted 
minimum. (For System/360 implementations, 
the magnitude of a floating-point value may 



248 



Page of GC28~20<*5~l f Issued September 15, 1970 by TNL GN28-3171 



not be less than approximately 10~**« or 

UNDERFLOW does not occur when equal num- 
bers are subtracted Coften called signifi- 
cance error) . 

Note that, for the TSS/360 PL/I compil- 
er, the expression X** (-Y) (where Y>0> is 
evaluated by taking the reciprocal of X**Yj 
hence, the OVERFLOW condition may be raised 
instead of the UNDERFLOW condition- 

Result : The invalid floating-point value 

is set to 0. 

Standard System Action : In the absence of 
an on-umt r the system prints a message and 
continues execution from the point at which 
the interruption occurred. 

Status: UNDERFLOW is enabled throughout 
the program, except within the scope of a 
condition prefix specifying NOUNDERFLOW. 

Normal Return : Upon normal termination of 
the on-unit for this condition, control 
returns to the point immediately following 
the point of interruption. 

The ZERODIVIDE Condition 



file delimiter of the file named in the GET 
or READ statement. It applies only to 
SEQUENTIAL files. 

If the file is not closed after ENDFILE 

occurs, then any subsequent GET or READ 
statement for that file, immediately raises 
the ENDFILE condition again. 

If ENDFILE is raised by an input/output 
statement using the EVENT option, the 
interruption does not take place until the 
execution of a subsequent WAIT statement 
for that event in the same procedure. 

Standard System Action : In the absence of 
an on~-unit # the system prints a message and 
raises the ERROR condition. 

Status : The ENDFILE condition is always 
enabled; it cannot be disabled* 

Normal Return : Upon the normal termination 
of the on-unit for the condition, execution 
continues with the statement immediately 
following the statement that caused the 
ENDFILE condition to be raised Cor, if END- 
FILE was raised by a READ with the EVENT 
option, control passes back to the WAIT 
statement from which the on-unit was 
invoked) . 



Description : The ZERODIVIDE condition 
occurs when an attempt is made to divide by 
zero. This condition is raised for fixed- 
point and floating-point division. 

Result ; The result of a division by zero 

is undefined. 

Standard System Action s In the absence of 
an on-unit, the system prints a message and 
raises the ERROR condition • 

Status : ZERODIVIDE is enabled throughout 
the program, except within the scope of a 
condition prefix specifying NOZERODIVIDE. 

Normal Return : Upon normal termination of 
the on-unit for this condition, control 
returns to the point immediately following 
the point of interruption. 



INPUT/OUTPUT CONDITIONS 



The QIDPAGB Condition 



General Format 



ENDPAGE C file- name) 



The "file name" must be the name of a 
file having the PRINT attribute. 

Description : The ENDPAGE condition is 
raised when a PUT statement results in an 
attempt to start a new line beyond the 
limit, specified for the current page. This 
limit can be specified by the PAGES I ZE 
option in an OPEN statement; if PAGES IZE 
has not been specified, a default limit of 
60 applies for the TSS/360 PL/I compiler. 
The attempt to exceed the limit may be made 
during data transmission I including asso- 



ciated format items. 



the POT statement 



is edit-directed) f by the LINE option, or 

by the SKIP option. ENDPAGE can also be 
raired by a LINE option or LINE format it en 

tlicrt specifies a line number 1 e*ia than the 
current line number. 



The input/ out put conditions are always 
enabled and cannot appear in condition pre- 
fixes; they can be specified only in ON f 
SIGNAL, and REVERT statements. 

The ENDFILE Condition 

General Format : ENDFILE (file-naue) 

Description : The ENDFILE condition can be 
raised during a GET or READ operation | it 
is caused by an attempt to read past the 



When ENDPAGE is raised, the car rent, line 
number is one greater than tii^t specified 
by the PAGESIZE option Cor 61, if the 
I default applies). The on-unit may start a 
new page by execution of a PAGE option or a 
PAGE format item, which sets the current 
line to 1. 

ENDPAGE is raised only once per page. 
Consequently, printing can be continued 
beyond the specified PAGESIZE after the 
ENDPAGE condition has been raised the first 
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time- if the on-unit does not start a new 
page, the current line number may increase 

indefinitely- If a subsequent LINE option 
or LINE format item specifies a line number 
that is less than the current line number r 
ENDPAGE is not raised, but a new page is 
started with the current line set to 1. 

If END PAGE is raised during data trans- 
miss ion, then, on return from the on-unit, 
the data is written on the current line, 
which may have been changed by the on-unit. 
If ENDPAGE results from a LINE or SKIP 
opt ion , then, on return from the on-unit, 
the action specified by LINE or SKIP is 
ignored. 

Standard System Action : In the absence of 
an on- unit, the system starts a new page. 
If the condition is signaled, execution is 
unaffected and continues with the statement 

following the SIGNAL statement. 

Status ; ENDPAGE is always enabled; it can- 
not be disabled. 

Normal Return : Upon the normal completion 
of the on-unit for this condition, execu- 
tion of the PUT statement continues in the 
manner described above. 

The KEY Condition 

General Format : KEY (file-name) 

Description : The KEY condition can be 
raised only during operations on keyed 
records. It is raised in any of the fol- 
lowing cases: 

1. The keyed record cannot be found. 

2. An attempt is made to add a duplicate 

key . 

3. The key is out of sequence. 

4. An error occurred in the conversion of 
the key. 

5. The key has not been specified 

correctly. 

6. No space is available to add the keyed 

record. 

If KEY is raised by an input/output 
statement using the EVENT option, the 
interruption does not occur until the 
execution of a subsequent WAIT statement 
for that event in the same procedure. 

The condition is not raised *f or a LOCATE 
statement until actual transmission is 
attempted (that is, immediately before 
execution of the next WRITE or LOCATE 
statement for the file, or immediately 



before the file is closed) ; until the error 
is corrected, the record cannot be trans- 
mitted, nor can any further operation take 
place for the file. 

A key sequence error cannot be detected 
by PL/ I on the first attempt to write to an 
indexed file that is reopened for sequen- 
tial out put 9 if the next operation on that 
file is close to it. 

Standard System Action : In the absence of 
an on-unit, the system prints a message and 
raises the ERROR condition. 

Status : KEY is always enabled? it cannot 
be disabled. 

Normal Return : Upon the normal completion 
of the on-unit for this condition, control 
passes to the statement immediately follow- 
ing the statement that caused KEY to be 
raised Cor, if KEY was raised by an input/ 
output statement with the EVENT option, 
control passes back to the WAIT statement 
from which the on-unit was invoked) . 



The NAME Conditio n 

Genera 1 Format : NAME (file- name) 

Description : The NAME condition can be 
raised only during a data-directed GET 
statement. It can be raised either when an 
identifier in the input stream does not 
have a counterpart in the data list of the 
GET statement or when the GET statement has 
no data list and an identifier that is not 
known in the block is encountered in the 
stream. 

NAME is raised at the time the unmatched 
identifier is encountered in the stream. 

The user may retrieve the data field 
(i.e., the identifier and its value) con- 
taining the unmatched identifier by using 
the built-in function DATAFIELD in the 
on-unit. 

Standard System Action : In the absence of 
an on-unit # the system ignores the incor- 
rect data field, prints a message, and con- 
tinues the execution of the GET statement. 

Status : NAME is always enabled; it cannot 
be disabled. 

Normal Return : Upon the normal completion 
of the on-unit for this condition 9 the 
execution of the GET statement continues 
with the next identifier in the stream. 

The PENDING Condition 

General Format : PENDING (file-name) 
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Description : Except when signaled, the 
PENDING condition can be raised only during 
execution of a READ statement for a TRAN- 
SIENT file. 

Note : Since TRANSIENT files are not sup- 
ported in TSS/360, the PENDING condition, 
although it will compile correctly, will 
result in an error diagnostic if executed. 



The RECORD Condition 

General Format : RECORD (filename) 

Description : The RECORD condition can be 
raised only during a READ, WRITE, or RE- 
WRITE operation. It is raised by any of 
the following: 

1. The size of the record is greater than 
the size of the variable. 

2. The size of the record is less than 
the size of the variable. 

3. A record of zero length has been read. 

1. An attempt is made to write a record 
of zero length. 

Note : Except when the length of the record 
variable is zero, the RECORD condition is 
not raised for consecutive unbuffered input 
files containing U-format records if read- 
ing forwards. 

if the size of the record is greater 
than the size of the variable, the excess 
data in the record is lost on input and is 
unpredictable on output. If the size of 
the record is less than the size of the 
variable, the excess data in the variable 
is not transmitted on output and is unal- 
tered on input. CThus # if a zero length 
record is read, the variable contains the 
same data that it contained before the read 
operation. ) If an attempt is made to write 
a record of zero length, the attempt is 
aborted, and, in effect, the statement is 
ignored. 

If RECORD is raised during transmission 
of an area, the area control field will 
contain incorrect information 

If RECORD is raised by an input/output 
statement using the EVENT option, the 
interruption does not occur until the 
execution of a subsequent WAIT statement 
for that event in the same procedure. 

Standard System Action : In the absence of 
an on- unit, the system prints a message and 
raises the ERROR condition. 

Status: RECORD is always enabled; it can- 
not be disabled. 



Normal Return : Upon normal completion of 
the on-unit c execution continues with the 
statement immediately following the one for 
which RECORD occurred Cor if RECORD was 
raised by an I/O statement with an EVENT 
option, control returns to the WAIT state- 
ment from which the on- unit was invoked) . 

The T RANSMIT Condition 

General Format : TRANSMIT I file-name) 

Description : The TRANSMIT condition can be 
raised during any input/output operation. 
It is raised by a permanent transmission 
error, and therefore signifies that any 
data transmitted is potentially incorrect. 
During input, the condition is raised after 
assignment of the potentially incorrect 
data item or record. During output, the 
condition is raised after the transmission 
of the potentially incorrect data item or 
record has been attempted. 

If TRANSMIT is raised by an input/ out put 

statement using the EVENT option, the 
interruption does not take place until the 
execution of a subsequent WAIT statement 
for that event in the same procedure* 

Standard System Action : In the absence of 
an on-unit, the system prints a message and 
raises the ERROR condition. 

Status : TRANSMIT is always enabled; it 
cannot be disabled. 

Normal Return : Upon the normal completion 
of the on- unit, processing continues as 
though no error had occurred, allowing 
another condition (e.g., RECORD/ la be 
raised by the statement or data item that 
raised the TRANSMIT condition, f If TRANS- 
MIT was raised by an in put /out put statement 
with an EVENT option, control returns to 
the WAIT statement from which the on-unit 
was invoked . 5 * 

The UNDEFINEDFILE Condition 

Gener al Format: UNDEFINEDFILE (file-name) 

De scription : The ONDEFINEDFII.E condition 

l!-, raised whenever an attempt .o open a 

file is unsuccessful. If the .it tempt is 
made by means of an OPEN statement that 

specifies more than one file name, attempts 
to open all other files in that statement- 
will be made before the condition is 
raised. If the condition is raised for 
more than one file in the same OPEN state- 
ment, on-units will be executed according 
to the order of appearance I taken from left 
to right) of the file names in that OPEN 
statement. 

if the condition is raised l>> an impli- 
cit file opening iii an input /out pat etite- 



Section 8: OU Conditions 251 



Page of GC28-20**5-l, issued September 15, 1970 by TNL GN28-3171 



merit without the EVENT option, then, upon 
normal return from the on-unit, processing 
continues with the remainder of the inter- 
rupted input/ out put statement. If the file 

was not opened in the on-unit, then the 
statement cannot be continued and the ERROR 

condition is raised* 

If the condition is raised by an impli- 
cit file opening in an input/output state- 
ment having an EVENT option , then the 
interruption occurs before the event vari- 
able is initialized- In other words, the 
event variable retains its previous value 
and remains inactive- On normal return 
from the on-unit, the event variable is 
initialized, that is f it is made active and 
its completion value is set to , , B (pro- 
vided the file has been opened in the on- 
unit) . Processing then continues with the 
remainder of the interrupted statement. 
However, if the file has not been opened in 
the on-unit, the event variable remains 
uninitialized, the statement cannot be con- 
tinued , and the ERROR condition is raised. 

For the TSS/360 PL/I compiler, some 
cases for which the UNDEFINEDFILE condition 

is raised are as follows: 

1. A conflict in attributes exists. 

2. The blocksize has not been specified. 

3. There is no recognizable DDEF command 
for a RECORD I/O file. 

Standard System Action : In the absence of 
an on-unit r the system prints a message and 

raises the ERROR condition. 

Status : UNDEFINEDFILE is always enabled? 
it cannot be disabled. 

Normal Return s Upon the normal completion 
of the final on-unit, control is given to 
the statement immediately following the 
statement that caused the condition to be 
raised (see "Description" for action in the 
case of an implicit opening) . 



PROGRAM-CHECKOUT CONDITIONS 

The CHECK Condition 

General Format s CHECK (name-list) 

The "name list" is one or more names 
separated by commas; a name may be a quali- 
fied name. Each name must be one of the 
following: 

1. An entry name 

2. A statement label constant 



An unsubscripted name representing an 
element, an array, or a structure 



The names appearing in a CHECK pref x.:i 
refer to the names known within the block 
to which the prefix is attached. A name 
cannot be a parameter or a variable having 
the DEFINED or BASED atrributes. 



Description ; The CHECK condition is ruined 
only within the scope of a CHECK condition 
prefix. Such a condition prefix may be 
prefixed only to a PROCEDURE or BEGIN 
statement. The CHECK condition is enabled 
separately for each name in the list of the 
CHECK prefix. For example, the prefix 
CHECK (A,B,C) is equivalent to CHECK (A); 
CHECK (B) : CHECK CO. Hence, the action 
specification can be controlled separately 
for each name. The REVERT statement can be 
used to change the action specification for 
one or more names in the list. Also, a 
NOCHECK prefix can be used to disable the 
CHECK condition for a specific name (like 
CHECK, NOCHECK can appear only as a prefix 
to a PROCEDURE or BEGIN statement). 

If the name of a structure or array of 
structures appears in the name list follow- 
ing CHECK, such a list is equivalent to one 
that contains, in the order in which they 
were declared, the elements of that struc- 
ture or array of structures. For example, 
if P is defined: 

DECLARE 1 P, 2 Q, 2 R, 2 S; 

then: 

CHECK CP) 
is equivalent to: 

CHECK (Q,R,S) 

The CHECK condition is raised within the 
scope of a CHECK prefix in any of the fol- 
lowing cases: 

1. If a name in the. CHECK prefix is a 
statement label constant, the condi- 
tion is raised and the interruption 
occurs prior to the execution of the 
statement to which the label is pre- 
fixed. If the label is prefixed to a 
DECLARE or FORMAT statement, the con- 
dition is not raised. 

2. If a name in the CHECK prefix is a 

variable (as specified in item 3 of 
the general format above) , the condi- 
tion is raised whenever the value of 
the variable, or a generation of any 
part of the variable, is changed by 
any statement within the scope of the 
prefix. 
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Specifically, if the identifier ID 
represents the variable, the condition 
is raised in the following cases: 

a. ID appears on the left-hand side 
of an assignment statement* (This 
applies to BY NAME assignment even 
if the name mentioned does not 
appear in the final expansion of 
the statement.) 

b. ID is set as a result of a pseudo- 
variable appearing on the left- 
hand side of an assignment 
statement. 

c. ID appears as the control variable 
of a DO-group or a repetitive 
specification in a data list Cor 
it is set as a result of a pseudo- 
variable appearing as the control 
variable of a DO- group or a repet- 
itive specification in a data 
list). 

d. ID appears in the data list of an 
edit-direct ed or list- directed GET 
statement. 
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f . 



ID is altered by data-directed 
input. 

ID appears in the REPLY option gf 
a DISPLAY statement. 



ly to the statement following the DO 
statement. If the DO specifies repet- 
itive execution, the interruption 
occurs each time the control variable 
changes value. 



g. ID appears in the STRING option of 
a PUT statement. 

h. ID is passed as an argument to a 
user-defined procedure, no inter- 
mediate argument is created, and 
the procedure terminates with a 
RETURN or END. 

i. ID appears in the KEYTO or INTO 
option of a READ statement. Note 
that if the READ statement has an 
EVENT option, the CHECK condition 
will not be raised. 

j. ID is a pointer variable and 
appears in a SET option. 

Note that in a, b, d, and e above, if 
ID is a structure, the CHECK condition 
is raised each time an element of that 
structure is given a value, but the 
interruption for each condition does 
not occur until after the statement 
that caused the condition to be raised 
has been executed completely. 

The condition is not raised under any of 
the following circumstances: 

a. If the value of a variable defined 
on ID or on part of ID changes in 
any of the ways described above. 

b. If the parameter that represents 
the argument ID changes value. 

c. If ID appears in a GO TO or RETURN 
statement or any statement that 
involves the execution of a GO TO 
or RETURN statement. 

d. If ID is set by the INITIAL 
attribute. 

Note that in all of the above con- 
texts, ID can appear in subscripted or 
qualified form. Note also that ID 
need not appear in the name list of a 
CHECK prefix; it only need represent a 
structure or element contained by, or 
containing, a name in the list. 

The interruption for a CHECK condition 
occurs after the statement that caused 
the condition to be raised has been 
executed. (Note that an IF statement 
is considered executed just prior to 
the execution of the THEN or ELSE 
clause.) If the statement is a DO 
statement, the interruption occurs 
each time control proceeds sequential- 



Only a data-direct 
a DO statement can 
to te raised more 
same appearance of 
a statement causes 
to be raised for s 
conditions will be 
to-right order of 
names . 



ed GET statement or 

cause a condition 
than once fcr the 
the same name. If 
a CHECK condition 
everal names, the 

raised in the left- 
appearance of the 



3. If a name in the CHECK prefix is an 
entry name, the condition is raised 
and the interruption occurs prior to 
each invocation of the entry point 
corresponding to the entry name. The 
condition is raised only if the entry 
point is invoked by the entry name 
given in the prefix. 

4. For the TSS/360 compiler, the number 
of characters in a qualified name to 
be used in CHECK name lists must not 
exceed 256. 

5. The maximum number of entries in a 
CHECK condition, whether in a prefix 
list or in an ON statement, is 510. 
The maximum number of data iterrs being 
checked at any point in the compila- 
tion varies between 2078- 2n and 3968- 
2n, where, n is the number of currently 
checked items which have the attribute 
EXTERNAL 

Result : When CHECK is raised, there is no 
effect on the statement being executed. 



Standard System Action : 
an on- unit, if the name 
a statement -lakel const 
label variable, a task 
an area variable, a loc 
entry name, then for th 
the name is printed on 
cases, the name and its 
printed on SYSOUT in th 
directed output. 



Note: 



In the absence of 
in the name list is 
ant, a statement- 
name, an event name, 
ator variable, or an 
is compiler, only 
SYSOUT; in all other 

new value are 
e format of data- 



Standard system action for the CHECK 
condition requires access to the variable; 
consequently, if SIGNAL CHECK is given for 
an unallocated variable, an error will 
result, as it would if the variable were 
accessed by an on-unit. 

Status : CHECK is disabled by default and 
within the scope of a NOCHECK condition 
prefix. It is enabled only within the 
scope of a CHECK prefix. 

Normal Return : Upon the normal completion 
of the on-unit for the CHECK condition, 
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execution continues immediately following 
the point at which the interruption 
occurred. 

The ST RINGRANGE Conditio n 

Definition: The STRINGRANGE condition is 
raised whenever the lengths of the argu- 
ments to a SUBSTR reference fail to comply 
with the rules described for the SUBSTR 
built-in function. It is raised for each 
such reference. 

Standard System Action : Execution con- 
tinues as described for normal return. 

Status: STRINGRANGE is disabled by default 
and within the scope of a N0STR1NGRANGE 
condition prefix. It is enabled only 
within the scope of a STRINGRANGE condition 
prefix. 

Normal Ret urn : On normal return from the 
en- unit, execution continues with a revised 
SUBSTR reference whose value is defined as 
fellows : 

Assuming that the length of the source 
strina (after execution of the on-unit, if 
specified) is k, the starting point is 1 , 
and the length of the substring is j; 

1 . If i is greater than k the value is 
the null string. 

2. If i is less than or equal to k, the 
value is that substring beginning at 
the nith character or bit of the source 
string and extending n characters or 
bits, where m and n are defined by: 

m=MAX(i,l> 

n=MAX(0,MIN( j + MIN(i, l)-l,k-m + l)) 

[if j is specified] 

n=k-m+l 

[if j is not specified) 

This means that the new arguments are 
forced within the limits. 

The values of i and j are established 
before entry to the on-unit; they are not 
reevaluated on return from the on-unit 

The SUBSCRIPTRANGE Condition 

Description : SUBSCRIPTRANGE can be raised 
whenever a subscript is evaluated and found 
to lie outside its specified bounds. If 
more than one subscript is associated with 
an identifier, e.g., A(I,J,K), SUBSCRIPT- 
RANGE is raised after each erroneous sub- 
script has been checked. Thus, if both I 
and J in the above example were in error, 
SUBSCRIPTRANGE would be raised after I was 
evaluated and again after J was evaluated. 



Result: When SUBSCRIPTRANGE has been 
raised, the value of the illegal subscript 
is undefined, and, hence, the reference is 
also undefined. 

Standard Sy stem Action: In the absence cf 
an on-unit r the system prints a message and 

raises the ERROR condition. 

Status : SUBSCRIPTRANGE is disabled by 
default and within the scope of a NGNSUB- 
SCRIPTRANGE condition prefix. It is 
enabled only within the scope of a SUB- 
SCRIPTRANGE condition prefix. 

Normal Return : Upon the normal completion 
of the on-unit for this condition, execu- 
tion continues immediately following the 
point, at which the condition occurred. 



LIST PROCESSING CONDITION 

The AREA Condition 

Description : The AREA condition is raised 
in either of the following circumstances: 

1. When an attempt is made to allocate a 
based variable within an area that 
contains insufficient free storage for 
the allocation. 

2. When an attempt is made to perform an 
area assignment, and the target area 
contains insufficient storage to 
accommodate the allocations in the 
source area. 

Result : If the condition occurs as the 
result of an attempted allocation, the 
allocation has no effect; if the condition 
occurs as a result of an area assignment, 
the contents of the target area are 
undefined. 

Standard System Action : In the absence of 
an on-unit, the system prints a message and 
raises the ERROR condition. 

Status : AREA is aisways enabled; it cannot 
be disabled. 



Normal Return: 



On normal return from the 



on-unit, the action is as follows: 

1. If the condition was raised by an 
allocation, the allocation is reat- 
tempted. If the on-unit has changed 
the value of a pointer qualifying the 
reference to the inadequate area so 
that it points to another area, the 
allocation is reattempted within the 
new area. 

2. If the condition was raised by an area 
assignment, or by a SIGNAL statement, 
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execution continues at the point of 

interruption. 



SYSTEM ACTION CONDITIONS 



The ERROR Condition 



Description ; The ERROR condition is raised 
under the following circumstances: 

1, As a result of the standard system 
action for an ON-condition for which 
that action is to "print an error mes- 
sage and raise the ERROR condition* 

2. As a result of an error (for which 
there is no ON-condition) occurring 
during program execution 



An afcnornal return from the on-unit will 
avoid any subsequent task termination pro- 
cesses and permit the interrupted task to 
continue. 

Standard System Action : In the absence of 
an on-unit, no action is taken? that is , 
execution of the interrupted statement is 
resumed. 

Status ; FINISH is always enabled; it can- 
not be disabled. 

Normal Return ; Upon the normal completion 
of the on-unit, execution of the inter- 
rupted statenent is resumed. That is f if 
FINISH is raised by any means other than 
SIGNAL FINISH, the normal completion of the 
FINISH on-unit terminates the program. 



3. As a result of a SIGNAL ERROR 
statement 



USER-NAMED CONDITION 



Standard System Action : For the TSS/360 
PL/I compiler, if the condition is raised 
in tne major task, the FINISH condition is 
raised, and subsequently the major task is 
terminated. If the condition is raised in 
any other task, that task is terminated. 

Status : ERROR is always enabled; it cannot 

be disabled. 

Normal Return : Upon the normal completion 
of the on-unit, the standard system action 
is taken. 

The FINISH Condition 



Descripti 
raised du 
which wou 
prog rani, 
an EXIT s 
RETURN or 
external 
raised by 
part of t 
ERROR con 
in the ta 
executed, 
condition 



on: The FINI 
ring executio 
Id cause the 
that is, by a 
tatement in t 

END statemen 
procedure. T 

SIGNAL FINIS 
he standard s 
dition. The 
sk in which t 

and any on-u 

is executed 



SH condition is 
n of a statement; 
termination of a PL/ I 

STOP statement, or 
he major task, or a 
t in the initial 
he condition is also 
H in any task, and as 
ystem action for the 
interruption occurs 
he statement is 
nit specified for the 
as part of that task. 



The CONDITION Co ndition 

General Format: CONDITION (identifier) 

The "identifier" must be specified ty 
the user. The appearance of an identifier 
with CONDITION in an ON, SIGNAL, or REVERT 
statement constitutes a contextual declara- 
tion for it; the identifier is given the 
EXTERNAL attritute. 

r escri pt ion: CONDITION is raised by a 
SIGNAL statement that specifies the appre- 
ciate identifier. The identifier speci- 
fied in the SIGNAL statement determines 
which CONDITION condition is to be raised. 

Stan dard System Action : In the absence of 
an on-unit for this condition, the system 
prints a message and continues with tne 
statement following SIGNAL. 

Status : CONDITION is always enabled; it 
• cannot be disabled. 

Normal Return : Upon the normal completion 
of the on-unit, execution continues with 
the statement following the SIGNAL state- 
ment that caused the interruption. 
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SECTION 9: ATTRIBUTED 



A name appearing in a PL/ I program may 
have one of many different meanings. It 
may, for example, be a variaLle referring 
to arithmetic data itens; it may be a file 
name; it may be a variable referring to a 
character string, or it may be a statement 
label or a variable referring to a state- 
ment label. 

Properties f or charact eristics , of the 
values a name represents (for example, 

arithmetic characteristics of data items 
represented by an arithmetic variable) and 
other properties of the name itself (such 
as scope, storage class, etc.) together 
make up tii«- set of attributes that can be 
associ =ted with a name. 

""he ^f Lributes enable the compiler to 
a^.Lg, a unique meaning to the identifier 
sre-iried in a DECLARE statement. For 
example, if the variable is an arithmetic 
data variable, the base, scale, node, and 
precision attributes must be associated 
with the name. Associated attributes are 
those specified in a DECLARE statement or 
assumed by default. 

This sect ion discusses the different 
attributes. The attributes art;- groujed by 
function and then detailed discussions, fol- 
low, in alphabetic order, showing the rules, 
defaults, and format for each attribute. 

At th e e nd o f t h e section, there is a 

table (figure **8A) summarizing the 
attributes. 



fcute for many identifiers* Factoring is 
achieved by enclosing the names in paren- 
theses, and following this by the set of 
attributes which apply. All factored 
attributes must apply to all of the names. 
No factored attribute can be overridden for 
any of the names, but any name within the 
list may be given other attributes so long 
as there is no conflict with the factored 
attributes. Factoring of attributes Is 
permitted only In the DECLARE statement, 
but not within an ENTRY attribute declara- 
tion. The number of left parentheses used 
for factoring attributes in DECLARE state- 
ments is limited to 73 in a compilation* 
The dimension attribute may be factored. 
The precision and length attributes can be 
factored only in conjunction with an asso- 
ciated keyword attribute. Factoring can be 
nested as shown in the fourth example 
below. Names within the parenthesized list 
are separated by commas. 

Note: Structure level numbers can also be 
factored, but a factored level number must 
precede the parenthesized list. 

DECLARE (A f B,C f D) BINARY FIXED (31); 

DECLARE SE DECIMAL ( 6, S ) f 

F CHARACTER (10)) STATIC; 

DECLARE 1 A, 2(B,C,D) (3,2) BINARY 
FIXED Cl r >), ...; 

DECLARE (CA,B) FIXEDC10), C FLOAT (5)) 
EXTERNAL; 



SPEC IFICATION OF ATTRI liUTES 

Attributes Cother than the dimension, 
length, and precision attributes) specified 
in DECLARE statements are separated by 
blanks. Except for the dimension, length, 
and precision attribute specifications, 
they may appear in any order. The dimen- 
sion attribute specification must immedi- 
ately follow the array nan.e; the length and 
precision attribute specifications must 
follow one of their associated attributes. 
A comma must follow the last attribute 
specification for a particular name Cor the 
name itself if no attributes are specified 
with it) , unless it is the last name in the 
DECLARE statement , in which case the semi- 
colon is used. 



FACTORING OF ATTRIBUTES 

Attributes common tc several names can 
be factored in a declaration to eliminate* 
repeated specification of the same attri- 



DATA ATTRIBUTEf 



PROBLEM DATA 



Attributes for problem data are used to 
describe arithmetic and string variables* 

Arithmetic variables have attributes that 
specify the base,- scale, mode, and preci- 
sion of the data items. String variables 

have attributes that specify whether the 
variable represents character strings or 
tit strings and that specify the length to 
be maintained. The arithmetic data attri- 
tut es are; 

BINARY] DECIMAL 

FIXED | FLOAT 

REAL | COMPLEX 

(precision) 

PICTURE 
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The string data attributes are: 

BIT] CHARACTER 

(length) 

VARYING 

PICTURE 

Other attributes can also be declared 
for data variables. The INITIAL attribute 
specifies the initial value to be given to 
the variable. The DEFINED attribute speci- 
fies that the data item is to occupy the 
same storage area as that assigned to other 
data. The ALIGNED and UNALIGNED attributes 
specify the positioning of data elements in 
storage. The storage class and scope 
attributes also apply to data. 

Other attributes apply only to data 
aggregates. For array variables, the 
dimension attribute specifies the number of 
dimensions and the bounds of an array. The 
LIKE attribute specifies that the structure 
variable being declared is to have the same 
structuring as the structure of the name 
following the attribute LUCE. 



PROGRAM CONTROL DATA 

Attributes for program control data spe- 
cify that the associated name is to be used 
by the user to control the execution of 
this program. The LABEL, TASK, EVENT, 
POINTER, OFFSET, and AREA attributes speci- 
fy program control data. 



ENTRY NAME ATTRIBUTES 

The entry name attributes identify the 
name being declared as an entry name and 
describe features of that entry point. For 
example, the attribute BUILTIN specifies 
that the reference to the associated name 
within the scope of the declaration is 
interpreted as a reference to the built-in 
function or pseudo- variable of the same 
name. The entry name attributes are: 

ENTRY 

RETURNS 

GENERIC 

BUILTIN 

REDUCIBLE 

IRREDUCIBLE 



FILE DESCRIPTION ATTRIBUTES 

The file description attributes estab- 
lish an identifier as a file name and 
describe characteristics for that file, 
e.g., how the data is to be transmitted, 
whether records are to be buffered. If the 
same file name is declared in more than one 
external procedure, the declarations must 
not conflict* unless one is declared with 
the INTERNAL attribute. 

The file description attributes are; 

FILE 

STREAM | RECORD 

INPUT | OUTPUT | UPDATE 

PRINT 

SEQUENTIAL 1 DIRECT 

BUFFERED | UNBUFFERED 

BACKWARDS 

ENVIRONMENT Coption-list) 

KEYED 

EXCLUSIVE 

Note that file description attributes, 
except for the ENVIRONMENT attribute, can 
be specified as options in the option list 
of the OPEN statement. 



SCOPE ATTRIBUTES 

whether or not a name may be known in 
another external procedure. The scope , 
attributes are EXTERNAL and INTERNAL. 

All external declarations for the same 
identifier in a program are linked as 
declarations of the same name. The scope 
of this name is the union of the scopes of 
all the external declarations for this 
identifier. 

In all of the external declarations for 
the same identifier, the attributes 
declared must be consistent, since the 
declarations all involve a single name. 
For example, it would be an error if the 
identifier ID were declared as an EXTERNAL 
file name in one block and as an EXTERNAL 
entry name in another block in the same 
program. 

The INTERNAL attribute specifies that 
the declared name cannot be known in any 
other block except those contained in the 
block in which the declaration is made. 
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The same identifier may be declared with 
the INTERNAL attribute in more than one 
block without regard to whether the attri- 
butes given in one block are consistent 
with the attributes given in another block, 
since the compiler regards such declara- 
tions as referring to different names. 



For 
see 

Names. 



'or a discussion of the scope of names. 
Part I, Section 7, "Recognition of 



STORAGE CLASS ATTRIBUTES 

The storage class attributes are used to 
specify the type of storage for a data 
variable. They are: 

STATIC 

AUTOMATIC 

CONTROLLED 

BASED 



ALP HABE TIC LIST OF ATTRIBUTES 

Following are detailed descriptions of 
the attributes, listed in alphabetic order. 
Alternative attributes are discussed 
together* with the discussion listed in the 
alphabetic location of the attribute whose 
name is the lowest in alphabetic order, A 
cross-reference to the combined discussion 
appears wherever an alternative appears in 
the alphabetic listing. 

ALIG NE D and UNALIGNED (Data Attributes) 

The ALIGNED and UNALIGNED attributes 
specify the positioning of data elements in 
storage, to influence speed of access or 
storage economy respectively. They may be 
specified for element, array, or structure 
variables. 

ALIGNED in System/360 implementations 
specifies that the data element is to be 
aligned on the storage boundary correspond- 
ing to its data type requirement. 

UNALIGNED in System/360 implementations 
specifies that the data element is to be 
stored contiguously with the data element 
preceding it, and that a fullword or dou- 
bleword item is to be mapped on the next 
available byte boundary in a similar manner 
to character strings of length 4 or 8. 

General format: 

ALIGNED | UNALIGNED 

General rules : 



1. Although they are essentially element 

data attributes, ALIGNED and UNALIGNED 
can be applied to any array or struc- 
ture. This is equivalent to applying 
the attribute to all contained ele- 
ments that are not explicitly declared 
with the ALIGNED or UNALIGNED 
attribute. 

2. Application of either attribute to a 
contained array or structure overrides 
an ALIGNED or UNALIGNED attribute that 
otherwise would apply to elements of 
the contained aggregate by having been 
specified for the containing 
structure. 

3. The LIKE attribute is expanded before 
the ALIGNED and UNALIGNED attributes 
are applied to the contained elements 
of the LIKE structure variable. The 
only ALIGNED and UNALIGNED attributes 
that are carried over from the LIKE 
structure variable Ci.e. , A in the 
example below) are those explicitly 
specified for substructures and ele- 
ments of the structure variable. 

Example: 

DECLARE 1 A ALIGNED, 

2 B, /♦ ALIGNED FROM A */ 

2 C UNALIGNED, 

3D; /* UNALIGNED FROM C */ 

DECLARE 1 X UNALIGNED LIKE A; 

DECLARE 1 Y LIKE A; 

The second declare statement is equi- 
valent to: 

DECLARE 1 X UNALIGNED, 

2 B, /* UNALIGNED FROM X •/ 

2 C UNALIGNED. 

3 D; /• UNALIGNED FROM C */ 

The third declare statement is equiva- 
lent to; 



DECLARE 1 Y, 
2 B, 

2 C UNALIGNED, 
3 D; 



/* ALIGNED BY DEFAULT •/ 
/* UNALIGNED FROM C **/ 



For overlay defining involving bit- 
and character- class data fsee Figure 
48) , both the defined item and the 
overlaid part of the base item must be 
unaligned . For all other types of 
defining, equivalent items must be 
either both ALIGNED or both UNALIGNED. 

The ALIGNED and UNALIGNED attributes 
of an argument in a procedure invoca- 
tion must match the attributes of the 
corresponding parameter* If these 
attributes of the original argument do 



258 



I Defined Item 



Page of GC28-2045-1, Issued September 15, 1970 by TNL GN28-3171 



Base Identifier 



h 



A coded arithmetic element 
variable 

An element label variable 

An element event variable 

An element task variable 

An element pointer variable 

An element offset variable 

An element area variable 

A bit class *■ variable 

A character class 2 variable 
A structure 



h 



An unsubscripted coded arithmetic element variable 
of the same base, scale, mode, and precision 

An unsubscripted element label variable 

An unsubscripted element event variable 

An unsubscripted element task variable 

An unsubscripted element pointer variable 

An unsubscripted element offset variable 

An unsubscripted element area variable 

Bit class 1 data that is neither a cross section of an 
array nor an array within an array of structures 

Character class 3 data that is neither a cross section 
of an array nor an array within an array of 

structures 

An identical structure whose makeup is such that 
matching pairs of items from the structures are 
valid examples for overlay defining of coded arith- 
metic, label, event, area, offset, and pointer ele- 
ment variables. The elements can also be strings 
or numeric character data items of matching 
lengths . 



*The bit class consists of: 

a. Fixed-length bit strings 

b. Unaligned structures consisting of items a or c 

c. Unaligned arrays consisting of items a or b 

2 The character class consists of: 

a. Numeric character data 

b. Fixed-length character strings 

c. Unaligned structures consisting of items a, b, or d 

d. Unaligned arrays consisting of items a, b, or c 



H 



Figure 48. Permissible Items for Overlay Defining 



7. 



not match those of the corresponding 
parameter in an ENTRY attribute 
declaration, a dummy argument is 
created, with the attributes specified 
in the ENTRY attribute declaration, 
and the original argument is assigned 
to it. 



If a based variable is used to refer 
to a generation of another variable, 
the ALIGNED and UNALIGNED attributes 
of both variables must agree. 



Default assumptions for ALIGNED and 
UNALIGNED are applied on an element 
basis. 

POINTER, OFFSET, LABEL, EVENT and AREA 
cannot be unaligned. 



Assumptions: 

1. Defaults are applied at element level. 
The default for bit-string data, 
character-string data, and numeric 
character data is UNALIGNED? for all 
other types of data, the default is 
ALIGNED. 

2. For all operators and built-in func- 
tions, the default for ALIGNED or 
UNALIGNED is applicable to the ele- 
ments of the result. 

3. Constants take the default for ALIGNED 
or UNALIGNED. 

AREA (Program Control Data Attribute) 

The AREA attribute defines storage that, 
on allocation, is to be reserved for the 
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allocation of based variables. Storage 
thus reserved can be allocated to and freed 
from based variables by naming the area 
variable in the IN option of the ALLOCATE 
and FREE statements- Storage that has been 
freed can be subsequently reallocated to a 
based variable. 

General format: 

AREA I (size) 1 

Syntax rule: 

The "size" can be an expression or an 
asterisk* 

General roles: 



declared area variables are given the 
AUTOMATIC attribute, The compiler 
requires that the variable named in 
the OFFSET attribute roust be based; if 
a nonbased area variable is named , the 
offset variable will be changed to a 
pointer variable. Hence f unless the 
variable named in the OFFSET attribute 
is explicitly declared, OFFSET effec- 
tively becomes POINTER, and a severe 
error occurs . 

AUTOMATIC. STATIC, CO NTR OLLED and BASED 
(Stor age^ cinss .^lAlfo— . _•_:'*. 

The storage class attributes are used to 
specify the type of storage allocation to 
be used for data variables. 



1. The area size for areas that are not 
of static storage class is given by an 
expression whose integral value speci- 
fies the number of units of storage to 
be reserved. The unit for System/360 
implementations is the byte. 

2. The size for areas of static storage 
class must be specified as a constant; 
for the compiler, it must be a decimal 

integer constant. 

3. An asterisk can be used to specify the 

size if the area variable being 
declared is controlled or is a para- 
meter. In the case of a controlled 
area variable declared with an 
asterisk , the size must be specified 
in the ALLOCATE statement used to 
allocate the area.' In the case of a 
parameter declared with an asterisk, 
the size is inherited from the 
argument . 

4 . Data of the area type cannot be con- 
verted to any other type; an area can 
be assigned to an area variable only. 

5. No operators can be applied to area 

variables. 

6. Only the INITIAL CALL form of the INI- 
TIAL attribute is allowed with area 
variables* 

7. An area variable cannot be unaligned. 
Assumptions: 

1. The implementation maximum size AREA 
is 32 f 767 bytes. If the size specifi- 
cation is omitted , a default value is 

assumed* For the TSS/360 PL/ 1 ' compil- 
er, this is 1000. 

2. An area variable can be contextual ly 
declared by its appearance i.i- an OFF- 
SET attribute or an IN option. Note, 

however, that all context ually 



AUTOMATIC specifies that storage is to 

be allocated upon each entry to the block 
to which the storage declaration is inter- 
nal,. The storage is released upon exit 
from the block. If the block is a proce- 
dure that is invoked recursively, the pre- 
viously allocated storage is "pushed down* 
upon entry; the latest allocation of 
storage is "popped up m upon termination of 
each generation of the recursive procedure 
Cfor a discussion of push-down and pop-up 
stacking, see Part I, 'section 6, ^Blocks, 
Flow of Control, and Storage Allocation"! . 

STATIC specifies that storage is to be 
allocated when the program is loaded and is 
not to be released until program execution 
has been completed* 

CONTROLLED specifies that full control 
will be maintained by the user over the 
allocation and freeing of storage by means 
of the ALLOCATE and FREE statements! Mul- 
tiple allocations of the sasre controlled 
variable, without intervening freeing , will 
cause stacking of generations of the 
variable- 

BASED, like CONTROLLED, specifies that 

full control over storage allocation and 
freeing will be maintained by the user, but 
by various methods that are described in 
Part I, Section 1«*, "Based Storage and List 
Processing. • Multiple allocations are not 
stacked but are available at any time; each 
can be identified by the value of a pointer 
variable. 

General format i 

STATIC | AUTOMATIC | 

CONTROLLED | BASED C pointier- var iable) 

General rules: 

1. Automatic and based variables can have 
internal scope only. Static and con- 
trolled variables may have either in- 
ternal or external scope* 
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2. Storage class attributes cannot be 

specified for entry names , file names, 

members of structures, or DEFINED data 
items. 



STATIC AUTOMATIC, and BASED attributes 
cannot be specified for parameters. 



*». Variables declared with adjustable 

array bounds, string lengths, or area 
sizes cannot have the STATIC 
attribute. 

5, For a structure variable, a storage 
class attribute can be given only for 
the major structure name. The attri- 
bute then applies to all elements of 
the structure or to the entire array 
of structures. If the attribute CON- 
TROLLED or BASED is given to a struc- 
ture, only the major structure and not 
the elements can be allocated and 
freed. 

6. The following rules govern the use of 
based variables: 

a. The pointer variable named in the 
BASED attribute must be a non- 
based, unsubscripted, element 
pointer variable. This applies to 
explicit pointer qualifiers also. 

b. Whenever a pointer value is needed 
to complete a based variable 
reference, and none is explicitly 
specified, the pointer variable 
named in the relevant BASED attri- 
bute is used. 

c. Based variables cannot have the 
INITIAL attribute. Based label 
arrays cannot be initialized by 
subscripted label prefixes. 

d. When reference is made to a based 
variable, the data attributes 
assumed are those of the based 
variable, while the qualifying 
pointer variable identifies the 
location of data. 

e. A based variable can be used to 
identify and describe existing 
data; to obtain storage by means 
of the ALLOCATE statement; or to 
obtain storage in an output buffer 
by means of the LOCATE statement. 

f. The relative locations of based 
variables allocated within an area 
can be identified by the values of 
offset variables, but these must 
be assigned to pointer variables 
for the purpose of explicit 
qualification. 



The EXTERNAL attribute cannot 
appear with a based variable 

declaration, but a based variable 
reference can be qualified by an 

external pointer variable. 



h. A based structure can be declared 
to contain only one adjustable 
bound or length specification. 
See "The REFER Option," in Part I, 
Section 14, "Based Storage and 
List Processing." 



i. Based variables cannot be trans- 
mitted using data-directed 
input /out put. 

j. The VARYING attribute cannot be 
applied to based variables., 

Assumptions : 

1. If no storage class attribute is spec- 
ified and the scope is internal, AUTO- 
MATIC is assumed. 

2. If no storage class attribute is spec- 
ified and the scope is external, STAT- 
IC is assumed. 

3. If neither the storage class nor the 
scope attribute is specified, AUTOMAT- 
IC is assumed. 

4. A pointer variable can be contextually 
declared by its appearance in the 
BASED attribute. 



BACKWARDS (File Description Attribute) 

The BACKWARDS attribute specifies that 
the records of a SEQUENTIAL INPUT file 
associated with a data set on magnetic tape 
are to be accessed in reverse order, i.e., 
from the last record to the first record. 

General format: 

BACKWARDS 

General rules: 

1. The BACKWARDS attribute applies to 
RECORD files only; that is, it con- 
flicts with the STREAM attribute. It 
implies RECORD and SEQUENTIAL. 

2. The BACKWARDS attribute applies only 
to files associated with data sets on 
magnetic tape. 



BASED (Storage Class Attjbute) 
See AUTOMATIC. 
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BINARY and DECIMAL (Arithmetic Data 
Attributes) 



The BINARY and DECIMAL attributes speci- 
fy the base of the data items represented 
by an arithmetic variable as either binary 
or decimal. 

General format: 

BINARY | DECIMAL 

General rule: 

The BINARY or DECIMAL attribute cannot 
be specified with the PICTURE attribute. 

Assumptions: 

Undeclared identifiers Cor identifiers 
declared only with one or more of the 
dimensions, UNALIGNED, ALIGNED, scope, and 
storage class attributes) are assumed to be 
arit • luetic variables with assigned attri- 
butes depending upon the initial letter. 
For identifiers beginning with any letter I 
through N r the default attributes are REAL 
FIXED BINARY (15,0), For identifiers - 
beginning with any other alphabetic 
character, the default attributes are REAL 
FLOAT DECIMAL (6). If FIXED or FLOAT and/ 
or REAL' or COMPLEX are declared, then DECI- 
MAL is assumed- The default precisions are 
those defined for System/360 
implementations. 

BIT and CHARACTER (String Attributes) 

The BIT and CHARACTER attributes are 

used to specify string variables* The BIT 
attribute specifies a bit string. The 
CHARACTER attribute specifies a character 
string. The length attribute for the 
string must also be specified. 

General format: 



BIT 



CHARACTER 



(length) {VARYING) 



General rules: 



The length attribute specifies the 
length of a fixed- length string or the 
maximum length of a varying -length 
string. 

The VARYING attribute specifies that 
the variable is to represent varying- 
length strings, in which case length 

specifies the maximum length. The 

current length at any time is the 
length of the current value* For the 
TSS/360 PL/1 compiler, the length of 
an uninitialized varying- length string 

is set to zero. VARYING may appear 
anywhere in the declaration of the 
string, and it may be factored. VARY- 



ING cannot be applied to based 
variables. 



3- The length attribute must immediately 
follow the CHARACTER or BIT attribute 
at the same factoring level with or 
without intervening blanks* 

4. The length attribute may be specified 
by an expression or an asterisk. 

If the length specification is an 
expression, it is converted to an 
integer when storage is allocated for 
the variable. 

The asterisk notation can be used for 
the length attribute specification to 
indicate that the length is specified 
elsewhere* For parameters or CON- 
TROLLED variables, the length can be 
taken from a previous allocation or, 
for CONTROLLED variables, it can be 
specified in a subsequent ALLOCATE 
statement. 

Only one adjustable string length 
specification can appear in the 
declaration of a based structure. See 
"The REFER Option 88 , in Part I, Section 
14. 

5. If a string has the STATIC attribute, 
the length attribute must be a decimal 
integer constant. 

6. If a string has the BASED attribute, 
the length attribute must be a decimal 
integer constant unless the string is 
a member of. a based structure dind the 
REFER option itj used, in which case 
one adjustable string length may be 
allowed. (See "The REFER "option" in 
Part I, Section l«i.) 

7. The BIT, CHARACTER, and VARYING attri- 
butes cannot be specified with the 
PICTURE attribute. 

8. The PICTURE attribute can be used 
instead of CHARACTER to declare a 
fixed-length character-string variable 
Cnee the PICTURE attribute). 

I 9. All of the string attributes should be 
declared explicitly unless the PICTURE 

I attribute is used. The default length 
for string data is 1. 



BUFFERED an d U NBUFFERED (File De scription 
Attributes) 

The BUFFERED attribute specifies that 
during transmission to and from external 
storage each record of a SEQUENTIAL RECORD 
file must pass through intermediate storage 
buffers. 
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The UNBUFFERED attribute specifies that 
such records need not pass through buffers. 
It does not, however, specify that they 
must not. For the TSS/360 PL/I compiler, 
hidden buffers will, in fact, be used if 
INDEXED is specified in the ENVIRONMENT 
attribute or if the records are 
variable- length. 



General format: 

BUFFERED | UNBUFFERED 
General rule: 



The BUFFERED and UNBUFFERED attributes 
can be specified for SEQUENTIAL RECORD 
files only. 

Assumption: 

Default is BUFFERED. 

BUILTIN (Entry Attribute) 

The BUILTIN attribute specifies that any 
reference to the associated name within the 
scope of the declaration is to be inter- 
preted as a reference to the built-in func- 
tion or pseudo-variable of the same name. 
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General format: 

) BUILTIN 

General rules: 

1- BUILTIN is used to refer to a built-in 
function or pseudo-variable in a block 
that is contained in another block in 
which the same identifier has been 
declared to have another meaning. 

2. If the BUILTIN attribute is declared 
for an entry name, the entry name can 
have no other attributes. 

3. The BUILTIN attribute cannot be 
declared for parameters. 

CHARACTER (String Attribute) 

See BIT. 

COMPLEX and REAL (Arithmetic Data 
Attributes) 

The COMPLEX and REAL attributes are used 
to specify the mode of an arithmetic vari- 
able. REAL specifies that the data items 
represented by the variable are to be real 
numbers. COMPLEX specifies that the data 
items represented by the variable are to be 
complex numbers, that is, each data item is 
a pair: the first member is a real number 
and the second member an imaginary number. 

General format: 

REAL (COMPLEX 

General rule: 

If a numeric character variable is to 
represent complex values, the COMPLEX 
attribute must be specified with the PIC- 
TURE attribute. The COMPLEX attribute is 
the only other arithmetic or string data 
attribute that can be specified with the 
PICTURE attribute. 

Assumption: 

Default is REAL. 
CONTROLLED (Storage Class Attribute) 

See AUTOMATIC. 
DECIMAL (Arithmetic Data Attribute) 

See BINARY. 
DEFINED (Data Attribute) 



The DEFINED attribute specifies that the 
variable being declared is to represent 
part or all of the same storage as that 
assigned to other data. The DEFINED attri- 



bute can be declared for element, array, or 
structure variables. 



General format: 

DEFINED base- identifier 

{ [subscript- listl 1 [POSITION 
(decimal-integer-constant ) ] } 

The "base identifier" is an unsubscripted, 
optionally qualified variable whose storage 
is also to be represented by the variable 
being declared. The "subscript list" is a 
specification used to determine the portion 
of a base identifier array that the cur- 
rently declared variable will represent. 
POSITION is discussed under the rules for 
overlay defining. 

Rules for defining: 

1. The INITIAL, storage class, and scope 
attributes cannot be specified for the 
defined item. The defined item must 
be a level 1 variable and it cannot be 
a parameter. The VARYING attribute 
must not be specified for either the 
defined item or the base identifier. 
It should be noted that although the 
base can have the EXTERNAL attribute, 
the defined item always has the INTER- 
NAL attribute and cannot be declared 
with any scope attribute. If the base 
is external, its name will be known in 
all blocks in which it is declared ex- 
ternal, but the name of the defined 
item will not. However, the value of 
the defined item will be changed if 
the value of the base item is changed 
in any block. 

2. The base identifier must always be 
known within the block in which the 
defined item is declared. The base 
identifier cannot have the DEFINED 
attribute. It can represent a minor 

1 structure. The TSS/360 PL/I compiler 
does not allow the base identifier to 
be controlled or based. 

There are two types of defining, corre- 
spondence defining and overlay defining. 
If iSUB variables are involved, or if both 
the defined item and base identifier are 
arrays with the same number of dimensions 
and the POSITION attribute is not speci- 
fied, correspondence defining is in effect. 
In all other cases, overlay defining is in 
effect. 

In correspondence defining: the ele- 
ments of the base identifier and the ele- 
ments of the defined item must have the 
same attributes. The lengths need not be 
the same; however, the length of the 
defined item must not be greater than the 
I length of the base item. The TSS/360 PL/I 
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compiler does not allow correspondence 
defining for arrays of structures. 



Correspondence Defining 

When correspondence defining has been 
specified, a reference to an element of the 
de Lined item is interpreted as a reference 
to the corresponding element of the base 
identifier. A reference to the defined 
array is interpreted as a reference to the 
aggregate of all of the tase elements that 
correspond to some element of the defined 
array. 

If there is no subscript list following 
the base identifier, then the correspon- 
dence is direct. In such a case, the 
arrays must have the same number of dimen- 
sions, and a reference to an element of the 
defined item would be interpreted as a 
reference to an element of the base with 
the same subscripts. 

If a subscript list follows the base 
identifier in the DEFINED attribute speci- 
fication, each subscript can be an expres- 
sion and each expression may contain 
references to the dummy variables indicated 
by iSUb. 

In the dummy variable iSUB, i is a deci- 
mal integer constant in the range 1 to n, 
where n is the number of dimensions of the 
defined item. Thus, ISUB represents sub- 
scripts of the first dimension of the 
defined array, 2SUB represents the second 
dimension of the defined array, and so 
forth. The subscript list following the 
name of the base array in the DEFINED 
attribute specification must contain the 
same number of subscript expressions as 
there are dimensions of the base array. 

At least one reference to iSUB must 
appear in the subscript list. An array 
defined by using iSUB variables in the sub- 
script list cannot be passed as an argu- 
ment. The base array can be passed, and an 
equivalent array can be defined on the cor- 
responding parameter. 

The base element corresponding to a 
defined element is obtained by replacing 
each iSUB in the subscript list by the 
integer value of the ith subscript of the 
defined element. 

The bounds of a defined array must be 
within the bounds of the base array. 

Overlay Defining 

Overlay defining specifies that the 
defined item is to occupy part or all of 
the storage allocated to the base. In this 
way, changes to the value of either vari- 
able may be reflected in the value of the 



other. Overlay defining is permitted 
between the items shown in Figure 48. 

Rules for overlay defining; 



1. 



For bit and cha 
POSITION attrib 
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2. 



POSITION (decimal- integer-constant) 

This specifies the position, in rela- 
tion to the start of the base, at 
which the defined item is to begin. 
If this attribute is omitted, POSITION 
(1) is assumed; that is, the defined 
item is to begin at the first position 
of the base. The maximum value of the 
integer constant in the POSITION 
attribute is 32,767. 

For bit and character class data, the 
extent of the defined item must not be 
larger than the extent of the base. 
Extent is calculated by summing the 
lengths of the parts of the data, 
including all individual elements of 
arrays, and, in the case of the 
defined item, adding n - 1 (where n is 
the position in relation to the start 
of the tase) . 



Order of Evaluation 

Evaluation proceeds as follows: 

1. Expressions specified in all attri- 
butes of the defined item (other than 
the DEFINED attribute) are evaluated 
on entry to the declaring block. 

2. Subscripts in the subscript list fol- 
lowing the base identifier are eva- 
luated when a reference to the defined 
item is made. 

Examples o f Defining 

1. DECLARE A(2Q,20), BC10) 

DEFINED A(2*1SUB, 2*1SUE) ; 

In this example of correspondence 
defining, B is a vector consisting of 
every even element in the diagonal of 
the array A. In other words, BCD 
corresponds to A(2,2), B(2) corres- 
ponds to A(4,4) f etc. 

2. DECLARE 1 P, 2 Q CHARACTER (10), 

2 R CHARACTER (100), 
PSTRING1 CHARACTER (110) 
DEFINED P; 
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In this example of overlay defining, 
PSTRING1 is a character string that 
represents the concatenation of the 
two character strings Q and R, which 
are elements of the structure P. Note 
that P has the PACKED attribute by 
default. 

3. DECLARE LIST CHARACTER C40), 

ALIST CHARACTER CIO) DEFINED LIST, 
BLIST CHARACTER 120) 

DEFINED LIST POSITION (21) f 
CLIST CHARACTER CIO) 

DEFINED LIST POSITION 111); 

In this example of overlay defining, 
ALIST refers to the first ten charac- 
ters of LIST, BLIST refers to the 
twenty-first through fortieth charac- 
ters of LIST, and CLIST refers to the 
eleventh through twentieth characters 
of LIST. 



U. DECLARE 1 



A, 

2 B FIXED, 
2 C FLOAT, 
X DEFINED A, 
2 Y FIXED, 
2 Z FLOAT,* 



General format: 

(bound I , bound ]...) 
where "bound" is: 

f I lower-bound : 1 u pper- bound) | * 

and "upper-bound" and "lower-bound" are 
element expressions . 

General rules: 

1* The number of bounds specifications 
indicates the number of dimensions in 
the array unless the variable being 
declared is contained in an array of 
structures, in which case it inherits 
dimensions from the containing 
structure. 

2, The bounds specification indicates the 
bounds as follows: 

a. If only the upper bound is given, 
the lower bound is assumed to be 1 

b. The lower bound must be less than 
or equal to the upper bound • 



In this example of overlay defining, Y 
refers to B and Z refers to C. 

Note : Although the language rules specify 
that the attributes (except for length) of 
the defined item must exactly natch the 
attributes of the base item, the TS5/360 
PL/I compiler allows a user to make an 
exception to this rule, under certain 
circumstances . 

If attributes declared for th* defined 
item differ from those of the ta.se identi- 
fier, the compiler notes this with a mes- 
sage at the ERROR level. For example: 

DECLARE A FIXED BINARYOl), 

B BIT (32) DEFINED A; 

Compilation of this DECLARE statement would 
cause an error message to be issutd by the 
compiler. However, execution of the pro- 
gram could be successful, and arithmetic 
operations performed upon h would result in 
the change of value of the bit-string varir 
able B. 



Dimension (Array Attribute) 

The dimension attribute specifies the 
number of dimensions of an array and the 
bounds of each dimension. The dimension 
attribute either specifies the bounds 
(either the upper bound or the upj er .jh<3 
lower bounds) or indicates, by u.*;o of an 
asterisk, that the actual bounds tor t h* 
array are to be taken from elc«-wh*»re. 



c. If asterisk notation is used, an 
asterisk must be used for each 
bounds specification of the array. 
An asterisk specifies that the 
actual bounds are to be specified 
in an ALLOCATE statement, if the 
variable is CONTROLLED, or in a 
declaration of an associated argu- 
ment, if the variable is a simple 
parameter. Thus, the asterisk 
notation can be used only fcr 
parameters and CONTROLLED 
variables. 
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The bounds of arrays declared STATIC 
must be optionally signed decimal 
integer constants. 

The bounds of arrays declared EASED 
must he optionally signed decimal 
integer constants unless the array is 
part of a based structure and the 
Nf-FIR option is used, in which case 
on* ad just..i hl^ hound specification is 
allowed. (See "The REFER Option" in 
Part I, Section 1 ** . ) 
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The dimension attribute roust immedi- 
ately follow the array name Cor the 
parenthesized list of names, if it is 
being factored). Int.* rveninq blanks 
are optional. 

If the asterisk notation is used to 
declare dimensions of an drray of 
structures, all dimension declarations 
within the major structure roust also 
be asterisks. 

Arrays are limited, for each dimen- ■ 

sion, to a lower bound of -32,768 and 

to an upper bound of 32,767. 



DIRECT and SEQUENTIAL CFile Descr iption 

Attributes) 

The DIRECT and SEQUENTIAL attributes 
specif v the manner in which the records in 
a data set associated with a RECCRD file 
aj.» !.( be accessed. SEQUENTIAL implies 
that, tae records are to be accessed accord- 
ing to their sequence in the dat<i set. 
(The records in an INDEX El) data set are 
processed in their logical sequence; the 
records in a CONSECUTIVE or REGIONAL data 
set are processed In their phy sical 
sequence.) DIRECT specifies that the rec- 
ords will always be accessed by use of a 
key; each record must, therefore, have a 
key associated with it. Either of these 
two attributes implies the RECCRD 
attribute* 

Note that DIRECT and SEQUENTIAL specify 
only the current usage of the file; they do 
not specify physical properties of the data 
set associated with the tile. The data set 
associated with a SEQUENTIAL file may actu- 
ally have keys recorded with the data. 
Most data sets accessed by DIRECT files are 
created by SEQUENTIAL files. 



ENTRY Attribute 

The ENTRY attribute specifies that the 
identifier beinq declared is an entry name* 

It also is used to describe the attributes 
of parameters of the entry point. 

General format: 

ENTRY [ (parameter-attribute-list 

i , parameter-attribute-list) . . . ) ] 

General rules: 

1. The ENTRY attribute with associated 
parameter attribute lists must be 
declared for any entry name that is 
invoked within the block if the attri- 
butes of any argument of the invoca- 
tion differ from the attributes of the 
associated parameter* This specifies 
that the compiler is to create the 
necessary dummy arguments • 

2. Each "parameter attribute list" 

describes the attributes of a single 
parameter. For example, the parameter 
attribute lists for the parameters in 

the following procedure: 

TEST: PROCEDURE CA # B ,C f D, E, F) ; 



DECLARE A 


FIXED DECIMAL (5) , 


B 


FLOAT BINARY CIS) , 


C 


POINTER, 


1- 


L, 


2 


P, 


2 


Q, 


3 


R FIXED DECIMAL, 


1 


E, 


2 


x # 


2 


Y r 


3 


z. 



FU) CHARACTER (10); 



General Format: 

DIRECT | SEQUENTIAL 
General rules: 

1. DIRECT files must also have the KEYED 
attribute (which is implied by 
DIRECT). SEQUENTIAL files may or may 

not have the KEYED attribute. 

2. The DIRECT and SEQUENTIAL attributes 
cannot be specified for files with the 

STREAM attribute. 

Assumptions : 

1. Default is SEQUENTIAL for RECORD 

files. 

2. If a file is implicitly opened by an 
UNLOCK statement, DIRECT is assumed. 



END TEST; 

could be declared as follows: 

DECLARE TEST ENTRY 

(DECIMAL FIXED (5), 
BINARY FLOAT (15), 



I. 

2. 
2, 
3 DECIMAL FIXED, 

9 

(4) CHARACTER (10)); 

3. The parameter attribute lists must 

appear in the same order as the para- 
meters they describe. If the attri- 
bute of any parameter need net be 
described, the absence of the corre- 
sponding parameter attribute list must 
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be indicated by a comma. C In the 

example above, the paraineter C has no 

parameter attribute list nor has the 
structure parameter E. ) If a paramet- 
er attribute list is absent, the argu- 
ment is assumed to match the 
parameter. 

The attributes may appear in any order 
in a parameter attribute list. For an 
array parameter attribute list, the 
dimension attribute must be the first 
specified, otherwise the attributes 
may appear in any order. For a struc- 
ture parameter attribute list, the 
level numbers must appear in the same 
order as the level numbers of the cor- 
responding parameter, and they must 
precede the attributes for each level; 
the attribute list numbers need not be 
the same as those of the parameter, 
but the structuring must be identical; 
the attributes for a particular level 
may appear in any order « 

Mote : Each attribute-list level numb- 
er together with any attributes speci- 
fied for the level, is delimited by a 
comma. (See example above.) 

The ENTRY attribute must be specified 
for any entry name that is declared 
elsewhere and not recognized as such 
within the block if any reference is 
made to that entry name (such as in an 
argument list) unless, within the 
block: 

a. The entry name appears in a CALL 
statement or a function reference 
with an argument list, either of 
which constitutes a contextual 
declaration of the ENTRY attri- 
bute, or 

b. The entry name is declared to have 
the RETURNS attribute, which 
implies ENTRY, or the BUILT1N 
attribute. The ENTRY attribute 
cannot be specified for a name 
that is given the BUILTIN or GEN- 
ERIC attributes. 

The ENTRY attribute must be specified 
or implied for an entry name that is a 
parameter . 

Expressions used for length or bounds 
in an ENTRY attribute -specification 
for non-CONTROLLED parameters are eva- 
luated upon entry to the block to 
which the declaration of the ENTRY 
attribute is internal. 

Factoring of attributes is not per- 
mitted within parameter attribute 
lists of an ENTRY attribute 
specification. 



9. The ENTRY attribute must appear for 

each entry name in a GENERIC attribute 

specif i cat ion • 

10. The ENTRY attribute can be declared 
for an internal entry name only within 
the block to which the name is 

internal. 

11. The maximum nesting of ENTRY attri- 
butes within an ENTRY or GENERIC 

attribute is 3. 

Assumptions: 

The ENTRY attribute can be assumed ei- 
ther context ually or by implication, as 
described in rule 2. The appearance of a 
name as a label prefix of either a PROCE- 
DURE statement or an ENTRY statement con- 
stitutes an explicit declaration of that 
identifier as an entry name. No defaults 
are applied for parameters unless attri- 
butes and/or level numbers are specified. 
If only a level number and/or the dimension 
attribute is specified for a parameter, 
FLOAT, DECIMAL* and REAL are assumed. 



ENVIRONMENT (File Description Attribute) 

See Part I, Section 9, "Stream- Oriented 
Transmission," and Part I, Section 10, 
"Record-Oriented Transmission." 

EVENT (Program Control Data Attribute) 

The EVENT attribute specifies that the 
associated identifier is used as an event 
name* Event names are used to investigate 
the current state of asynchronous input/ 
output operations. They can also be used 
as program switches. 

Note : In TSS/360, asynchronous I/O can 
occur only with CONSECUTIVE SEQUENTIAL 
UNBUFFERED files. 



General format: 

EVENT 
General rules: 

1. An identifier may be explicitly 
declared with the EVENT attribute in a 
DECLARE statement. It may be contex- 
tually declared by its appearance in a 
WAIT statement, in a DISPLAY state- 
ment, or in various input/output 
statements (see Part I, Section 8, 
"Input and Output, ") 

2. Event names may also have the follow- 
ing attributes: 

Dimens ion 
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Scope Cthe default is INTERNAL) 



Storage class Cthe default is 
AUTOMATIC) 

DEFINED (event names may only be 
defined on other event names) 

An event variable has two separate 
values: 

a* A single bit which reflects the 
completion value of the variable. 
• 1"B indicates complete, 'O'B 
indicates incomplete. 

b. A fixed-point value of default 

precision CC15 # 0) for the TSS/360 
PL/ I compiler) which reflects the 

status value of the variable. A 
zero value indicates normal, non- 
zero indicates abnormal status. 

The values of the event variable can 
be separately returned by use of the 
COMPLETION and STATUS built-in func- 
tions. The COMPLETION function 
returns a bit-string value correspond- 
ing to the completion value of the 
variable i STATUS returns a fixed 
binary value corresponding to the sta- 
tus value. 

Assignment of one event variable to 
another causes both the completion and 

status values to be assigned. Conver- 
sion between event variables and any 

other data type is not possible. 

Event variables may be elements of an 
array. Arrays containing event 
variables may take part in assignment, 
provided that this would not require 
conversion to or from event data. 

The values of the event variable can 

be set by one of the following means: 

a. Use of the COMPLETION pseudo- 
variable , to set the completion 

value* 

b. Use of the STATUS pseudo- variable, 

to set the status value. 

c. Event variable assignment. 

d. By a statement with the EVENT 
option. 

e. By a WAIT statement for an event 

variable associated with an input/ 
output event. 

f * By the termination of a task with 
which the event variable is 
associated. 



g. By closing a file on which an 
input/output operation with an 
event, option is in progress. 

6. On allocation of an event variable, 

its status and couple ti on values are 
undefined. 

7. An event variable may be associated 
with an event, that is, a task or an 

input/output operation, by means of 
the EVENT option on a statement. The 
variable remains associated with the 
event until the event is completed. 
For an input/ out put events the event 
is completed during the execution of 
the WAIT for the associated event. 
During this period the event variable 
is said to be active- It is an error 
to associate an active event variable 
with another event , or to modify the 
completion value of an active event 
variable by event variable assignment 
or by use of the COMPLETION 
pseudo-variable . 

8. It is an error to assign to an active 

event variable (including an event 
variable in an array, structure, or 
area) by means of an input/output 
statement . 

9. On execution of a CALL- statement with 
the EVENT option f the program in which 
the CALL is executed will be abnormal- 
ly terminated. In TSS/360 f event 
variables may be successfully asso- 
ciated only with input /output 

' operations. 

10. On execution of an input/output state- 
ment with the EVENT option, the event 
variable, if inactive, is set to zero 
status value and to incomplete. The 
sequence of these two assignments is 
uninterruptable and is completed 
before any transmission is initaited 
but after any action associated with 
an implicit opening is completed. An 
input/output event variable will not 
be set complete until either the ter- 
mination of the procedure that 
initiated the event or the execution, 
by that procedure, of a WAIT statement 
naming the associated event variable. 
The WAIT operation delays execution of 
this task until any transmission asso- 
ciated with the event xs termi.nat.ed. 
If no input /out put conditions are to 
be raised for the operation, the event 
variable is set complete and is no 
longer active. If any input/ out. put 
conditions are to be raised, the event 
variable is set to have a status value 
of 1 and the relevant conditions are 
raised. On normal return from the 
last on-unit entered as a result of 
these conditions, or on abnormal 
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return from one of the on-units, the 
event variable is set complete and is 
no longer active. 



11, Event variables cannot be unaligned. 

EXCLUSIVE (File Description Attribute) 

The EXCLUSIVE attribute specifies that 
records in a data set associated with a 
DIRECT UPDATE file may be locked by an 
accessing task to prevent other tasks from 
interfering with an operation. 

Under TSS/360 the EXCLUSIVE attribute 
need not be declared, since record locking 
is automatic and cannot be suppressed by a 
NOLOCK option. 

General format: 



EXCLUSIVE 



EXTERNAL and INTERNAL (Scope Attributes) 

The EXTERNAL and INTERNAL attributes 
specify the scope of a name. INTERNAL spe- 
cifies that the name can be known only in 
the declaring block and its contained 
blocks. EXTERNAL specifies that the name 
may be known in other blocks containing an 
external declaration of the same name. 

General format: 

EXTERNAL | INTERNAL 

General rules: 



1. 



When a major structure name is 
declared EXTERNAL in more than one 
block, the attributes of the structure 
members must be the same in each case, 
although the corresponding nember 
names need not be identical. 



2. 



Members of st 
INTERNAL attr 
declared with 
However, a re 
<ex*ernal stru 
name known to 
reference, is 
to that ireir.be 
the external 
of whether th 
names are ide 



ructures always 

ibute and canno 

any scope attr 

ference to a me 

cture, using th 

the block cont 

effectively a 

r in all blocks 

name is known, 

e corresponding 

nt ical. 



have the 
t be 

ibut€fT ^ 
mber of an 
e member 
aininqL.the 
reference 

in which 
regardless 

member 



Assumptions: 



INTERNAL is assumed for entry names of 
internal procedures and for variables with 
any storage class. EXTERNAL is assumed for 
file names and entry names of external pro- 
cedures. User-defined condition names are 
assumed to be EXTERNAL. 



FILE (File Description Attribute) 

The FILE attribute specifies that the 
identifier being declared is a file name. 

General format: 

FILE 

Assumptions: 

The FILE attribute can be implied by any 
of the other file description attributes. 
In addition, an identifier may be contextu- 
ally declared with the FILE attribute 
through its appearance in the FILE option 
of any input/output statement, or in an ON 
statement for any input/output condition. 

FIXED and FLOAT (Arithmetic Data 
Attributes) 

The FIXED and FLOAT attributes specify 
the scale of the arithmetic variable being 
declared. FIXED specifies that the vari- 
able is to represent fixed-point data 
items. FLOAT specifies that the variable 
is tc represent floating-point data items. 

General fcrnat: 

FIXED) FLOAT 

General rule: 

The FIXED and FLOAT attributes cannot be 
specified with the PICTURE attribute. 

Assumptions: 

Undeclared identifiers (or identifiers 
declared only with one or more of the 
dimension, PACKED, ALIGNED, scope, and 
storage class attributes) are assumed to be 
arithmetic variables with assigned attri- 
butes depending upon the initial letter. 
For identifiers beginninq with any letter I 
through N, the default attributes are REAL 
FIXED BINARY (15,0). For identifiers be- 
ginning with any other alphabetic character 
the default attributes are REAL FLOAT DECI- 
MAL (6). If BINARY or DECIMAL and/or REAL- 
or COMPLEX are specified, FLOAT is assumed. 
The default precisions are those defined 
fcr Systew/36a implementations. 

FLOAT (Arithmetic Data Attribute) 

See FIXED. 

GENERI C (Entry Name Attribute) 

The GENERIC attribute is used to define 
a nane as a family of entry names, each of 
which is referred to by the name being 
declared. When the generic name is 
referred to, the proper entry name is 
selected, based upon the arguments speci- 
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fied for the generic name in the procedure 

reference- 



General format: 



GENERIC (entry- name- declaration 

[ r entry- name- declaration] 



.) 



General rules: 



1. 



6. 



No other attributes can be specified 
for the name being given the GENERIC 
attribute- 
Each "entry name declaration" follow- 
ing the GENERIC attribute corresponds 
to one member of the family, and has 
the form: 

entry-name attribute-list 

Thv,; "attribute list" of each entry 
name declaration specifies attributes 
of the entry name. It must include 
the ENTRY attribute. It may optional- 
ly have INTERNAL, EXTERNAL, and 
RETURNS attributes. No entry name 
declaration can have the GENERIC 
attribute, nor can it have the BUILTIN 
attribute* 



Each 
ify 

each 
with 
ly t 
decl 
entr 
same 
bloc 
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entry name 
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parameter, 
in a GENERIC 
he same as a 
aration. Th 
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identifier 
k if the ent 
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declaration must spec- 
r level numbers for 
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ny ether ENTRY 
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can appear in the same 
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ion of a con- 
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parameter. 



The selection of a particular entry 
name is first based on the number of 
arguments in the reference to the 
name. The following attributes are 

then considered in choice of generic 
members: 

Base 

Scale 



Mode 

Precision 
PICTURE 

LABEL (but not label list) 

Number of dimensions (but not 
bounds) 

CHARACTER C but not length) 

BIT (but not length) 

VARYING 

ENTRY (but not parameter descrip- 
tion or other attributes of entry 
names) 

FILE (but no other FILE attributes) 

ALIGNED 

UNALIGNED 

AREA (but not size) 

OFFSET Chut not specified area 
variable) 

POINTER 

TASK 

EVENT 

Generic entry names (as opposed to 
references) may be specified as argu- 
ments to nongeneric procedures if the 
invoked entry name is explicitly 
declared with the ENTRY attribute. 
This ENTRY attribute must specify that 
the appropriate parameter is an entry 
name and must specify, by means of a 
further ENTRY attribute, the attri- 
butes of all its parameters. This 
enables a choice to be made of which 
family member is to be passed. 

There is a limitation on the number of 
family members and arguments which may 
be associated with a GENERIC entry 
name. The value given by evaluating 
the following formula must not exceed 
700: 

n 

3n+8 J> a- x +8MAXia Xt aa. ...... ,a n > + 3d 

1 

where n = the number of family 
members 

a = the number of arguments 

relating to the ith family 
member 
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d = the greatest function 

nesting depth at which an 
invocation of the GENERIC 
entry name appears. 

9. For the TS3/360 compiler, the maximum 
nesting of ENTRY attributes with a 
GENERIC attribute is 3. 

INITIAL (Data Attribute) 

The INITIAL attribute has two forms. 
The first specifies an initial constant 
value to be assigned to a data item when 
storage is allocated to it. The second 
form specifies that, through tne CALL 
option, a procedure is to te invoked to 
perform initialization at allocation. 

General format: 

1. INITIAL (item [, item]...) 

2. INITIAL CALL entry-name 

[argument- list] 

General rule: 

The INITIAL attribute cannot be given 
for entry names, file names, defined data, 
structures, parameters, or based variables. 

Rules for form 1: 

1. In this discussion, the term "con- 
stant" denotes one of the following: 

[ + |-1 arithmetic-constant 

character- string- constant 

bit-string- const ant 

[+ |-] real- cons tant{+ | -} imaginary- 
constant 

2. Only one constant value can be speci- 
fied for an element variable; more 
than one can be specified for an array 
variable. A structure variable can be 
initialized only by separate initiali- 
zation of its elementary names, wheth- 
er they are element or array 
variables. 

3. Constant values specified for an array 
are assigned to successive elements of 
the array in row-major order (final 
subscript varying most rapidly). 

** . If too many constant values are speci- 
fied for an array, excess ones are 
ignored; if not enough are specified, 
the remainder of the array is not 
initialized. 

5. Each item in the list can be a con- 
stant, an asterisk denoting no ini- 



tialization for a particular element, 
or an iteration specification. 

Tne iteration specification has one cf 
the following general forme: 

(iteration- factor ) constant. 

(iteration- factor) ( item (, item) . . . ) 

(iteration-factor) * 

The "iteration factor" specifies the 
nuirter cf times the constant, or item 
list, is to be repeated in the ini- 
tialization of elements of an array. 
If a constant follows the iteration 
factor, then the specified number of 
elements are to be initialized with 
that value. If a list of iterrs fol- 
lows the iteration factor, tnen tne 
list is to be repeated the specified 
number of times, with each iterr 
initializing an element of the array. 
If an asterisk follows the iteration 
factor, then the specified number of 
elements are to be skipped in the ini- 
tialization operation. 

The iteration factor can be an element 
expression, except for STATIC data, in 
which case it must be an unsigned dec- 
imal integer constant. When storage 
is allocated for the array, the expre- 
ssion is evaluated to give an integer 
that specifies the number of 
iterations. 

A negative or zero iteration factcr 
causes no initialization. 
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nitialization cf a string array, 
ly one parenthesized eleirent 
ssion precedes the string initial 
, the expression is interpreted 

a string repetition factor for 
tring; that is, it is interpreted 
part of the specification of the 

for a single element cf the 
Consequently, for an expres- 
to cause initialization of more 
one element of a string array, 
the string repetition factor and 
teration factor must be explicit- 
ated, even if the spring repeti- 
factor 



is (1 



sider the foilowi 



)_. For exarrple, ccn- 
ng: 



((2) f A') is equivalent tc CAA') 
(for a single element) 

<(2)(1)'A') is equivalent to 
('A 1 , 'AM (for two elements) 

10. Iterations may be nested. 

11. Label constants given as initial 
values for label variables must, be 
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known within the block in which the 
label variable declarations occur. 
STATIC label variables cannot have the 
INITIAL attribute. 



12. An alternate method of initialization 
is available for elements of arrays of 
non-STATIC statement label variables; 
an element of a label array can appear 
as a statement prefix, provided that 
all subscripts are optionally signed 
decimal integer constants. The effect 
of this appearance is the initializa- 
tion of that array element to a value 
that is a constructed label constant 
for the statement prefixed with the 
subscripted reference. This statement 
must be internal to the block contain- 
ing the declaration of the array. 
Only one form of initialization can be 
used for a given label array. If 
CHECK is specified for a label array 
and the elements of the label array * 
are initialized by a label prefix, the 
CHECK condition is not raised at 
initialization. 

13. For the TSS/360 PL/I compiler, 
character-string or bit-string data 
having the STATIC attribute cannot be 
initialized with complex values. 

14. This form of the INITIAL attribute 
cannot be used in the declaration of 
locator or area variables. 

15. Initialization of LABEL variables on 
structures with the LIKE attribute 
requires careful handling, particular- 
ly as the implementation does not pro- 
vide the result specified by the lan- 
guage. A structure A is declared, 
using the LIKE attribute, to be iden- 
tical to a structure E. Structure B 
contains a LABEL variable that is ini- 
tialized, using the INITIAL attribute, 
to the value of a LABEL constant. The 
initial value of the corresponding 
LABEL variable in A is the initial 
value of the LABEL constant known in 
the block containing the declaration 
of B, not A. 



For example: 



DCL 1 B, 

2 L LABEL INITIAL (Ll); 



LI: 



; /*B.L 



Ll*/ 



BEGIN; 

DCL A LIKE B; 



Ll: .; /*A.L IS GIVEN THE VALUE OF 
Ll IN STRUCTURE B*/ 



END; 
Rules for form 2: 

1. The "entry name" and "argument list" 
passed must satisfy the condition 
stated for prologues as discussed in 
Part I, Section 6, "Blocks and Flow of 
Control." 

2. Form 2 cannot be used to initialize 
STATIC data. 



Examples: 
a . 



c. 



d. 



e. 



DECLARE SWITCH BIT (1) 
INITIAL ri'B); 

DECIARE MAXVALUE INITIAL (99), 
MINVALUE INITIAL (-99); 

DECLARE A (100,10) INITIAL 

((920)0, (20) ((3)5,9)); 

DECLARE TABLE (20,20) INITIAL 
CALL INITIALIZE (X,Y); 

DECLARE 1 A (8) , 

2 B INITIAL (0), 

2 C INITIAL ((8)0) ; 

DECLARE Z(3) LABEL; 



Z(l) 



Z(2) 



Z(3) 



EXIT 



IF X = Y THEN GO TO EXIT; 



A + B + C * D; 



A + 10; 



GO TO Z ( I ) ; 



RETURN ; 



Example c results in the following: 
each of the first 920 elements of A is set 
to 0, the next 80 elements consist of 20 
repetitions of the sequence 5,5,5,9. 

In Example d, INITIALIZE is the name of 
a procedure that sets the initial values of 
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elements in TABLE, X 
passed to INITIALIZE. 



and Y are arguments 



In Exairple e, B and C inherit a dimen- 
sion of (8) but, whereas only the first 
element of B is initialized, all the ele- 
ments of C are initialized. 



In the last example, transfer is made to 
a particular element of the array Z by giv- 
ing I a value of 1,2, or 3. 



INPUT, OUTPUT, and UPDATE (File Description 
Attributes) 



IRREDUCIBLE and REDUCIBLE 

These attributes cause no action in the 
TSS/360 PL/I compiler other than tc irrply 
the ENTRY attribute. 

KEYED (File Description Attribute) 



The KEYED attribute specifies that the 
options KEY, KEYTO and KEYFROM may be used 
in statements that refer to the file to 
access records. These options indicate 
that keys are involved in accessing the 
records in the file. 

General format: 



The INPUT, OUTPUT, and UPDATE attributes 
indicate the function of the file. INPUT 
specifies that data is to be transmitted 
from external storage to the program. OUT- 
PUT specifies that data is to be trans- 
mitted from the program to external 
storage. UPDATE specifies that the data 
can be transmitted in either direction; 
that is, the file is both an input and an 
output file. 

General format: 

INPUT | OUTPUT | UPDATE 

General rules: 

1. A file with the INPUT attribute cannot 
have the PRINT attribute. 

2. A file with the OUTPUT attribute can- 
not have the BACKWARDS attribute. 

3. A file with the UPDATE attribute can- 
not have the STREAM, BACKWARDS, or 
PRINT attributes. A declaration of 
UPDATE for a SEQUENTIAL file indicates 
the update-in-place mode: a record 
can be updated only by a READ state- 
ment followed by a corresponding 
REWRITE statement. 

Assumptions : 

Default is INPUT. The PRINT attribute 
implies OUTPUT. The EXCLUSIVE attribute 
implies UPDATE. 

The following assumptions are made when 
a file is implicitly opened by an input/ 
output statement : 

i WRITE, LOCATE, PUT OUTPUT 
READ, GET INPUT 

DELETE, REWRITE, UNLOCK UPDATE 



INTERNAL (Scope Attribute) 
See EXTERNAL. 



KEYED 
General rules: 

1. A KEYED file cannot have the attri- 
butes STREAK or PRINT. 

2. The KEYED attribute can be specified 
only for RECORD files associated with 
data sets on direct-access devices. 

3. The KEYED attribute must be specified 
for every file with which any of the 
options KEY, KEYTO, and KEYFROM is 
used. It need not be specified if 
none of the options are to be used, 
even though the corresponding data set 
may actually contain recorded keys. 

Assumption: 

The DIRECT and EXCLUSIVE attributes 
imply KEYED. 

LABEL (Program Control Data Attribute) 

The LABEL attribute specifies that the 
identifier being declared is a label vari- 
able and is to have statement labels as 
values. To aid in optimization of the 
object program, the attribute specification 
rray also include the values that the name 
can have during execution of the program. 

General format: 



LABEL [ (statement-label-constant 
C, statement- label- constant] 



.)] 



General rules: 



If a list of statement label constants 
is given, the variable can have as 
values only members of the list. The 
label constants in the list must be 
known in the block containing the 
declaration. 

The number of statement label con- 
stants specified by the LABEL attri- 
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bute is limited to 125 in any particu- 
lar label list. 

If the variable is a parameter, its 
value can be any statement label vari- 
able or constant passed as an argu- 
ment. If the argument is a label 
variable, the value of the label pa- 
rameter can be any value permitted for 
the label variable that is passed. 

An entry name cannot be a value of a 
label variable. 

The parenthesized list of statement 

label constants can be used in a LABEL 

attribute specification for a label 

array. A subscripted label specifying 

an element of a label array can appear 

as a statement label prefix, if the 

label variable is not STATIC, but it 

cannot appear in an END statement 

after the keyword END. For further 3. 

information, see general rule 12 in 

the discussion of the INITIAL 

attribute. 

The INITIAL attribute cannot be speci- 
fied for STATIC label variables. <* . 

Labels cannot be unaligned. 



Length (String Attribute) 

See BIT. 

LIKE (Structure Attribute) 

The LIKE attribute specifies that the 
name being declared is a structure variable 
with the same structuring as that for the 
name following the attribute keyword LIKE. 
Substructure names, elementary names, and 
attributes for substructure names and ele- 
mentary names are to be identical. 

General format; 

LIKE structure-variable 

General rules: 



5. 



The "structure variable" can be a 
major structure name or a minor struc- 
ture name. It can be a qualified 6. 
name, but it cannot be subscripted. 

The "structure variable" must be known 
in the block containing the LIKE 
attribute specification. The struc- 
ture names in all LIKE attributes are 
associated with declared structures 
before any LIKE attributes are 
expanded. For example: 7. 

DECLARE 1 A, 2 C, 3 £, 3 F, 
1 D, 2 C, 3 G, 3 H; 



BEGIN; 

DECLARE 1 A LIKE D, 1 B LIKE A.C; 



END? 

These declarations result in the 
following: 

1 A LIKE D is expanded to give: 

1 A, 2 C, 3 G, 3 H 
1 B LIKE A.C is expanded to give: 

IB, 3 E, 3 F 

Neither the "structure variable" nor 
any of its substructures can be 
declared with the LIKE attribute, nor 
may the "structure variable" have been 
completed by the LIKE attribute. 

Neither additional substructures nor 
elementary names can be added to the 
created structure? any level number 
that immediately follows the "struc- 
ture variable" in the LIKE attribute 
specification in a DECLARE statement 
must be algebraically equal to or less 
than the level number of the name 
declared with the LIKE attribute. 

Attributes of the "structure variable" 
itself do not carry over to the 
created structure. For example, 
storage class attributes do not carry 
over. If the "structure variable" 
following the keyword LIKE represents 
an array of structures, its dimension 
attribute is not carried over. Attri- 
butes of substructure names and ele- 
mentary names, however, are carried 
over; contained dimension and length 
attributes are recomputed. An excep- 
tion is that this does not apply to 
the INITIAL attribute for any elements 
of a label array that has been ini- 
tialized by prefixing to a statement. 

If a direct application of the 
description to the structure declared 
LIKE would cause an incorrect con- 
tinuity of level numbers (for example, 
if a minor structure at level 3 were 
declared LIKE a major structure at 
level 1) the level numbers are modi- 
fied by a constant before application. 

The LIKE attribute is expanded before 
the ALIGNED and UNALIGNED attributes 
are applied to the contained elements 
of a structure. 
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OFFSET and POINTER (Program Control Data 
Attributes) 

The OFFSET and POINTER attributes 
reference to identify a particular alloca- 
tion of the based variable. Offset 
variables identify a location relative to 
the start of an area; pointer variables 
identify any location, including those 
within areas. 



9. Only the INITIAL CALL form of the INI- 
TIAL attribute is allowed in locator 
declarations . 

10. Offset variables cannot be used to 
qualify a based reference. 

I 11. For the TSS/360 PL/I compiler, the 
area variable named in an OFFSET 
attribute must be of based storage 
class. 



General format: 



POINTER (OFFSET (area-variable) 



General rules: 

1. A pointer variable can be explicitly 
declared in a DECLARE statement, or i t 
can be contextually declared by its 
appearance as a pointer qualifier, by 
its appearance in a BASED attribute, 
or by its appearance in a SET option. 

2. An offset variable must be explicitly 
declared. 

3. The value of a pointer variable can be 
set in any of the following ways*: 

a. With the SET option of a READ 
statement; 

b. By a LOCATE statement; 

c. By an ALLOCATE statement; 

d. By assignment of the value of 
another locator variable, or a 
locator value returned by a user- 
defined function; 

e. By assignment of an ABDR or NULL 
built-in function value. 

4. The value of an offset variable can be 
set only by assignment of the value of 
another locator variable or the value 
of the NULLO built-in function. 

5. Locator variables cannot be operands 
of any operators other than the com- 
parison operators = and 1 =. 

6. Locator data cannot be converted to 
any other data type, but pointer can 
be converted to offset, and vice 
versa . 

7. A locator value can be assigned on^Ly 
to a locator variable. When an offset 
value is assigned to an offset vari- 
able, the area variables named in the 
OFFSET attributes are ignored. 

8. Locator data cannct be transmitted 
using STREAM input/output. 



12. Pointer variables and offset variables 
cannot be unaligned. 

Assumption: 

The variable named in the OFFSET attri- 
bute is contextually declared to have the 
AREA attribute, but its storage class will 
be automatic; hence, it will net ccnforir to 
general rule 11, above. For the TSS/360 
PL/I compiler, therefore, an offset 
declaration without an accompanying expli- 
cit area declaration will result in an 
error. (See also "AREA (Program Control 
Data Attribute) , " in this section.) 



OUTPUT (File Description Attribute) 
See INPUT. 

PICTURE (Data Attribute) 

The PICTURE attribute is used to define 
the internal and external formats of 
character-string and numeric character data 
and to specify the editing of data. Numer- 
ic character data is data having an arith- 
metic value tut stored internally in 
character form. Numeric character data 
irust be converted to coded arithmetic 
before arithmetic operations can be 
performed. 

The picture characters are described in 
Part II, Section 4, "Picture Specification 
Characters." 

General format: 

PICTURE 

• character-picture- specification* 
'numeric-picture -specification' 

A "picture specification," either character 
or numeric, is composed of a string of pic- 
ture characters enclosed in apostrophes . 
An individual picture character may be pre- 
ceded by a repetition factor, which is a 
decimal integer constant, n, enclosed in 
parentheses, to indicate repetition of the 
character n times. If n is zero, the 
character is ignored. Picture characters 
are considered to be grouped into fields , 
some of which contain subfields. 
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General rules: 



2. 



The "character pi 
is used to descri 
data item. Three 
used: A # indicat 
ciated position i 
contain any alpha 
blank; X, indicat 
ciated postion ma 
character; and 9, 
associated positi 
decimal digit or 
picture specifica 
least one A or X. 
ture specif icatio 
with no contained 

Example ; 



cture specification" 
be a character-string 

characters may be 
ing that the asso- 
n the data item may 
faetic character or a 
ing that the asso- 
y contain any 

indicating that the 
on may contain any 
a blank. A character 
tion must include at 

Each character pic- 
n is a single field 

subf ields . 



DECLARE ORDER# PICTURE 

' AA(3)9X99X(<*)9' ; 

This declaration specifies that values 
of ORDER# are to be character strings 
of length 13, The string consists of 

two letters, three digits, any 
character, two digits, any character, 
and four digits. For example, the 
character string *G 42-63-0024' would 
t_ i. t t.nis description. 

Editing and suppression characters are 
not allowed in character picture spe- 
cif i cat ions . Each picture specifica- 
tion character must represent an actu- 
al character in the data item. 

The "numeric picture specification" is 
used to describe a character item that 
represents either an arithmetic value 
or a character-string value, depending 
upon its use. A numeric picture spe- 
cification can consist of one or more 
fields, some of which can be divided 
into subf ields. A single field is 
used to describe a fixed-point number 
or the mantissa of a floating-point 
number. Either may be divided into 
two subf ields, one describing the 
integer portion, the other describing 
the fractional portion. For floating- 
point numbers, a second field is 
reguired to describe the exponent; it 
cannot be divided into subf ields. A 
second field may optionally be used 
with fixed-point numbers to indicate a 
scaling factor. Four basic picture 
characters can be used in a numeric 
picture specification: 

9 indicating any decimal digit 

V indicating the assumed location of 
a decimal point. It does not spe- 
cify an actual character in the 
character-string value of the data 

item. The V also indicates the end 



of a subfield of a picture 
specification. 

K indicating, for floating-point data 
items, that the exponent should be 
assumed to begin at the position 

associated with the picture 
character following the K. It does 
not specify an actual character in 
the character- string value of the 
data item, either an E or a sign. 
The K delimits the two fields of 
the specification. 

E indicating # for floating-point data 
items, that the associated position 
will contain the letter E to indi- 
cate the beginning of the exponent. 
The E also delimits the two fields. 

In addition to these characters, zero 
suppression characters, editing char- 
acters, and sign characters may be 
included in a numeric picture specifi- 
cation to indicate editing. Editing 
characters are not a part of the ari- 
thmetic value of a numeric character 
data item, but they are a part of its 
character-string value. Repetition 
factors are allowed in numeric 
specifications . 



A numeric charact 
only a decimal ba 
precision are spe 
characters. The 
cannot be specifi 
with base, scale, 
butes. If the mo 
character data is 
the COMPLEX attri 
itly stated. 



er data item can have 
se. Its scale and 

cified by the picture 
PICTURE attribute 
ed in combination 
or precision attri- 

de of the numeric 
COMPLEX, however, 

bute must be explic- 



Tne following paragraphs indicate the 
combinations of picture characters for 
different arithmetic data formats. 

a. Real decimal fixed-point items are 
described in the following general 
form; 

PICTURE f [9j . . . [V] [9] . . . 

CFCI+I-] integer)]' 

The optional field of the picture 
specification, beginning with the 
letter F together with a parenthe- 
sized, optionally signed decimal 
integer constant, is a scaling 
factor that indicates the location 
of an assumed decimal point if 
that location is outside the actu- 
al data item. The scaling factor 
has an effect similar to the 
exponent of a floating-point num- 
ber; it indicates that the assumed 
decimal point is "integer" places 
to tne right (or left, if nega- 
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tive) of the position otherwise 
indicated. 



Sign, editing, and zero suppres- 
sion picture characters can be 
included in a fixed-point specifi- 
cation. The V cannot appear more 
than once in a specification, 
although it may be used in combi- 
nation with the decimal point (.) 
or comma C,) editing characters, 
which cause insertion of a period 
or comma. If no V is included, 
the decimal point is assumed to be 
to the right of the rightmost 
digit. Only one sign indication 
can be included in the first field 
(the actual sign of the integer in 
a scaling factor is allowed addi- 
tionally) . The specification must 
include at least one digit 
position. 

Example: 

DECLARE A PICTURE ' 999V99 1 ; 

This specification describes nu- 
meric character items of five 
digits, two of which are assumed 
to be fractional digits. 

Real decimal floating-point items 
are described by the following 
general form: 

PICTURE 

1 [91... [V] l9J...fE|K}9[9]' 

Both the mantissa field and the 
exponent field must each contain 
at least one digit position. The 
exponent field can contain no more 
than two digits, since System/360 
implementations allow only two 
digits in the exponent field of a 
decimal floating-point number. If 
arithmetic data items are to be 
assigned to the described vari- 
able, the exponent field must con- 
tain both of the allowed digit 
specification characters, or the 
second digit of the exponent field 
will be lost and the SIZE condi- 
tion will be raised. 

Sign, editing, and zero suppres- 
sion picture characters can be 
included in a floating-point spe- 
cification. One sign indication 
is allowed for each field. Only 
one V is allowed, and it can 
appear in the first field only. 
As with fixed-point specifica- 
tions, the V may appear in combi- 
nation with the decimal point 
editing character C as .V or V.). 



c. Complex numeric character data is 
described using the general form: 

PICTURE 'real- picture' COMPLEX 

The "real picture" is a specifica- 
tion for either a decimal fixed- 
point or a decimal floating-point 
data item. The single picture 
specification describes both parts 
of a complex number. 

The precision of a numeric character 
variable is dependent upon the number 
of digit positions, actual and condi- 
tional. Digit positions can be speci- 
fied by the following characters: 

9 an actual digit character 

Z V 



Y 



conditional digit characters spe- 
cifying zero suppression 



I \ digit characters specifying an 

overpuncn 
R " 



conditional digit drifting 
characters 



Each but the first conditional digit 
drifting character in a drifting 
string specifies a digit position. A 
conditional digit drifting character 
used alone does not specify a digit 
position. 

Precision of a fixed-point variable is 
(p,q), where jd is the number of digit 
positions in the picture specification 
and £ is the number of digit positions 
following V. Precision of a floating- 
point variable is (p) , where j: is the 
number of digit positions preceding 
the E or K. Indicated st*atic editing 
characters or insertion characters do 
not participate in the specification 
of precision, but they must be counted 
in the number of characters if the 
data item is written as output or 
assigned internally to a character 
string. 

A variable representing sterling data 
items can be specified by using a nu- 
meric picture specification that con- 
sists of three fields, one each for 
pounds, shillings, and pence. The 
pence field may be divided into two 
subfields. Data so described is 
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stored in character format as three 
contiguous numbers corresponding to 
each of the three fields. If any 
arithmetic operations are specified 
for the variable, its value is con- 
verted to coded fixed-point decimal 
representing the value in pence. 
Sterling picture specifications have 
the following form: 

PICTURE 

"G [editing-character-11 • . . 

M pounds-field 

M (separator- 13 . . . 

shillings- field 

M [separatcr-21. .. 
pence-field 

Cediting-character-21 . - . ' 

Picture specification characters, 
editing characters, and separators can 
foe used in any of these fields and are 
discussed in Part II, Section 4, "Pic- 
ture Specification Characters." 

The precision (p,q) of a sterling nu- 
meric discussed in Part II, Section 4, 
"Picture Specification Characters." 

q = nuirber of fractional digits in 

the pence field 

p = 3 +q+ (number of digit positions, 
actual and conditional, in the 

pounds field) 

P OINTER (Program Control Data Attribute) 

See OFFSET. 
POSITIO N (Data Attribute) 

See DEFINED. 

Precision (Arithmetic Data Attribute) 

The precision attribute is used to spe- 
cify the minimum number of significant 
digits to be maintained for the values of 
the data items, and to specify the scale 
factor (the assumed position of the binary 
or decimal point) . The precision attribute 
applies to both binary and decimal data. 

General format: 

(number-of-digits [ , scale-factor] ) 

The "number of digits" is an unsigned 
decimal integer constant and "scale factor" 
is an optionally signed decimal integer 
constant. The precision attribute specifi- 
cation is often represented, for brevity. 



as (p,q), where £ represents the "number of 
digits" and _g represents the "scale 

General rules; 



1. 



3. 



The precision attribute must immedi- 
ately follow, with or without inter- 
vening blanks, the scale (FIXED or 
FLOAT) , base (DECIMAL or BINARY) , or 
mode (REAL or COMPLEX) attribute at 
the same factoring level. 

The number of digits specifies the 
number of digits to be maintained for 
data items assigned to the variable. 
The scale factor specifies the number 
of fractional digits. No point is 
actually present; its location is 
assumed. 

The scale factor can be specified for 
fixed-point variables only; the nurrber 
of digits is specified for both fixed- 
point and floating-point variables. 

When the scale is FIXED and no scale 
factor is specified, it is assumed to 
be zero; that is, the variable is to 
represent integers. 

The scale factor of a variable, or of 
an intermediate result of type FIXED, 
must be in the range -128 and +127. 



The scale factor 

it can be larger 
digits. A negati 
always specifies 
point assumed to 
to the right of t 
digit. A positiv 
that is larger th 
digits always spe 
with the point as 
places to the lef 
actual digit. In 
vening zeros are 
not stored; only 
of digits are act 



can be negative, and 
than the number of 
ve scale factor C-q) 
integers, with the 
be located cj places 
he rightmost actual 
e scale factor (q) 
an the number of 
cifies a fraction, 
sumed to be located c[ 
t of the rightmost 

either case, inter- 
assumed, but they are 
the specified nurrber 
ually stored. 



7. The precision attribute cannot be spe- 
cified in combination with the PICTURE 
attribute. 

8. The maximum number of digits allowed 
for System/36 implementations is 15 

for decimal fixed- point data, 31 for 
binary fixed-point data, 16 for decim- 
al floating-point data, and 53 for 

binary floating-point data. 

Assumptions : 

The defaults for System/360 implerrenta- 
tions are as follows; 

(5,0) for DECIMAL FIXED 
(15,0) for BINARY FIXED 
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(6) for DECIMAL FLOAT 
(21) for BINARY FLOAT 



PRINT (File Description Attribute) 

The PRINT attribute specifies that the 
data of the file is ultimately to be 
printed. The PAGE and LINE options of the 
PUT statement and the PAGESIZE option of 
the OPEN statement can be used only with 
files having the PRINT attribute. These 
options are described in Part II , Section 
10 , "Statements." 

General format: 

PRINT 

General rules: 

1. The PRINT attribute implies the OUTPUT 
and STREAM attributes. 

2. The PRINT attribute conflicts with the 
RECORD attribute. (However, through 
the use of the DDEF command, RECORD 
files can be associated with tne 
printer. ) 

3. The PRINT attribute causes the initial 
data byte within each record to be 
reserved for USASI printer control 
characters. These control characters 
are set by the PAGE, SKIP, or LINE 
format items or options. 

Assumption: 

If no FILE or STRING specification 
appears in a PUT statement, the standard 
1 output file SYSPRINT is assumed. 



REAL (Arithmetic Data Attribute) 

See COMPLEX. 

RECORD and STREAM (File Description 
Attributes) 

The RECORD and STREAM attributes specify 
the kind of data transmission to be used 
for the file. STREAM indicates that the 
data of the file is considered to be a con- 
tinuous stream of data items, in character 
form, to be assigned from, the stream to 
variables, or from expressions into the 
stream. RECORD indicates that the file 
consists of a collection of physically 
separate records, each of which consists of 
one or more data items in any form. Each 
record is transmitted as an entity to or 
from a variable. 

General format: 

RECORD I STREAM 



General rules: 

1. A file with the STREAM attribute can 
be specified only in the OPEN, CLOSE, 
GET, and PUT statements. 

2. A file with the RECORD attribute can 
be specified only in the OPEN, CLOSE, 
READ, WRITE, REWRITE, LOCATE, UNLOCK, 
and DELETE statements. 

3. A file with the STREAM attribute can- 
not have any of the following attri- 
butes: UPDATE, DIRECT, SEQUENTIAL, 
BACKWARDS, BUFFERED, UNBUFFERED, 
EXCLUSIVE, and KEYED, any of which 
implies RECORD. 

4. A file with the RECORD attribute can- 
not have the PRINT attribute. 

Assumptions: 

Default is STREAM. If a file is implic- 
itly opened by a READ, WRITE, REWRITE, 
UNLOCK, or DELETE statement, RECORD is 
assumed. 

Reducible 

See IRREDUCIBLE. 

RETURNS (Entry Name Attribut e) 

The RETURNS attribute may be specified 
in a DECLARE statement for an entry name 
that is used in a function reference within 
the scope of the declaration. It is used 
to describe the attributes of the function 
value returned when that entry name is 
invoked as a function. 

General format: 

RETURNS (attribute...) 

It is used in the following manner: 

DECLARE entry-name 

[ ENTRY-att ribute- speci f i cat ion] 
RETURNS (attribute. . . ) ; 

General rules: 

1. The "ENTRY attribute specification" 
consists of the keyword ENTRY with or 
without associated parameter attribute 
lists. If parameter attribute lists 
are not required, the keyword ENTRY is 
optional, since the RETURNS attribute 
implies the ENTRY attribute. 

2. The attributes in the parenthesized 
list following the keyword RETURNS are 
separated by blanks. They must agree 
with the attributes specified in the 
RETURNS option Of the PROCEDURE or 
ENTRY statement to which the entry 
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name is prefixed- If the attributes 
of the actual value returned do not 
agree with those declared with the 
RETURNS attribute, no conversion will 

be performed. 

3. Only arithmetic, string, locator, 
AREA, and PICTURE attributes can be 
specified, 

4. Length attribute specifications are 
evaluated on entry to the block con- 
taining the RETURNS attribute 
specification. 

5. Unless default attributes for the 
entry name apply, any invocation of a 
function must appear within the scope 
of a RETURNS attribute declaration for 
the entry name- For an internal func- 
tion, the RETURNS attribute can be 
specified only in a DECLARE statement 
that is internal to the same block as 
the function procedure. 

6. RETURNS is mandatory for function pro- 
cedures when function value attributes 

are explicitly specified. 

Assumptions: 

if the RETURNS attribute is not speci- 
fied within the scope of a function 
reference, the defaults assumed for the 
returned value are FIXED BINARY (15,0) if 
the entry name begins with any of the let- 
ters I through N; otherwise, the defaults 
are FLOAT DECIMAL (6). Default precisions 
are those defined for System/360 
implementations. 



SEQUENTIAL (File Description Attribute) 
See DIRECT. 

STATIC (Storage Class Attribute) 
See AUTOMATIC. 

STREAM (File Description Attribute) 

See RECORD. 

TASK (Program Control Data Attribut e) 

The TASK attribute was designed to 
describe a variable that may be used as a 
task name, to test or control the relative 
priority of a task. Since multitasking is 
not PL/I-controlled in TSS/360, any attempt 
to execute a statement making use of this 
attribute will cause abnormal termination 
of the program. 

UNALIGNED (Data Attribute) 

See ALIGNED. 
UNBUFFERED (File Description Attribute) 

See BUFFERED. 
UPDATE (File Description Attribute) 

See INPUT. 
VARYING (String Attribute) 

See BIT. 
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The following figure presents a summary of TSS/360 PL/I attributes. Throughout this 
figure* Column 5 (•conflicts with') lists only those attributes of the same class as the 
attributes in discussion. For example: data attributes are not listed as conflicting 

with any file attributes. 



Attribute and 
Abbreviat Ion 



Specified for 
Name:., of 



in I i led cy or 
Aj»:;uii«~hI for 



Implies or 
Assumed with 



Conflicts with 



Default 

Considerat ions 



H 



ALIGNED 



eleircnt t array 

structure vat: 
a bleu and pa- 
ra we tori". 



UNAL 



Default applied at 
element level; UNAL 
for bit, character, 
pictured data, ALIGNED 
for all other types; 
constants take defaults 



aj:ea ICsizeM 
"size" nay be 
element expression 
with AUTC or CTL 



level- one art-. 

variables and 
parao.et ern 



find 
ide 
in 

at 
st, J 
CJ Fh 

but 



€ c la red 

nt if iers 
IN option 
ALLOC 

tement and 
Ski rittri- 
r specif i- 
ion 



INIT without 

CALL option 



Default size is 1000 

bytes 



f- 



AUTOMATIC 

AUTO 



level -one 
variables 



.STATIC, CTL, BAT, ED, 
EXT, PEF, parameter: 



Default is AUTO unless 
EXT is specified, in 
which case, STATIC is 
assumed 



- + - 



BACKWARDS 



SEgL 

iNPiri 



RECORD 
tape ti i 



FILE,RECORL, 

SE^L, INPUT 
KXT 



STREAK, LIRECT 
OUTPU1 ,PRINT,EXCL ( 
UPDATE, KEYED 



BASED (ptr-var) 

CSee REFER 
option in Chapter 
14: Based 

Variables and List 
Processing) 



level-one 
vol in Lies 



.STATIC, CTL, AUTO 
EXT, INIT, OFFSET, 
DfcF , parameter , 
adjustatl* extPntf 
except with REFFR 



_— + __. 

*■ i i:\ Under 1 ,ir ed 
ray | ident if iers 
{with initial 
| 1 1 ■ t t « • i 1 
t hruugh N 
(.i | | li es al:;o 
to f unc t ion 
♦ •nt r y names) 



- + - 



Default storage class 
is AUTO unless EXT is 

specified, in which 
case, STATIC is 
assumed- Can cause 
contextual declaration 
of pointer variable 



BINARY 
BIN 



coded aril hrr-« 
element or ar 
variables and 

prj rametei s 



LEC, PIC 



r- 



Defaults for partly 
declared arithmetic 
variables are FLOAT 
DEC REAL unless a 
precision attribute 
specification follow- 
ing the base or mode 
attribute includes a 
scale factor, in which 
case, FIXEC is assumed 



BIT(lgth) [VARING] 
•lgth" may be 

element expres- 
sion fcr AUTO or 
CTL, asterisk for 

CTL or parameter, 
or REFER for 

BAS ED 



bit- string 

element cr ji 
variables and 
parameters 



ray 



NO 

str 



defa 

ing 



ults for any 

attributes 



r- 



BUFFERED 

BUF 



SE^L RECORD 
files, 



FILE.RtCCRL 

SEwL.EXT 



STREAM, DIRECT, 
PRINT, UNBUF,EXCL 



BUF is default for 
SEOL files 



BUILT IN 



built-in 

functions 



h 



any other att r i- 
hute, parameter r 



CHARACTER (lgth) 

{VARYING] 
CHAR 

"lgth* may be 
element expression 
for AUTO or CTL, 
asterisk for CTL 
or parameter, or 
REFER for BASED 



character-str 

element or ar 
variables and 
parameters 



ing 

ray 



BIT, PIC 



No defaults for any 
string attribute 



1 Figure 48A. Summary of Attributes (Pait 1 of 
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„_„____, — . — __- 


_ T . . T -- . . ... 


_ T , .. . 1 


| Attribute and 


|Specified for 


| Implied by or| Implies or | 


(Default j 


| Abbreviat ion 


(Names of 


j Assumed for 


j Ass iirreri withjconf 1 ictj; with 


(considerations j 


I.—-.™.— _______ 


+—.--— — — 


-A_-__ .... 


_+_ . + — — — . 


_+____-_-— ____________._ H 


JCOMFI.FX 


farithroet ir 




| |RhAL 


fREAL is default for | 


fCPLX 

1 

1 

L___ ._ ,. . . , 


| element or 

j array variables 

|and parameter:. 
X— _—- .. , . 


_JL . , __ 


_A j. _ 


| arithmetic variables j 

_a_,_. __._._._. _.__._.___ __ __j 


r 


,j._.___, __ _ 


.j. - _. 


_y _.__ ^ 


_^. — .«___._._.__._. ^ 


f CONTROL LLC 


| level-one v.iri- 




j | STATIC, AUTO, RASED 


{Default storage class J 


|CTL 

I 

\ 

I 


jafoles and pu~ 
j ra met err. 






fis AUTO unless EXT is { 
j specified, in which } 
(case, STATIC is | 
(assumed { 


l_________________.. 


A.-.™——™.— 


~T -— ~ 


.4 X _ 


_+__ —___ H 


j DECIMAL 


j coded arithmetic 


: j Undeclared 


| |BIN,PIC 


(Defaults for partly | 


{ DEC 


j element or arraj 


^ | ident if iers 




J declared arithmetic j 


! 


{variables and 


jwit.h any ini 


- | ' | 


| variables are FLOAT, { 


1 

1 
I 


| parameters 


jtial letter 
j except I 
| through N 




| DEC, REAL, unless a | 
j precision attribute } 
| following a base or f 


! 




j ia\ plies als 


°l 1 


(mode attribute in- | 


i 




| to function 




{eludes a scale factor, | 


1 

! 




| entry names.) 




fin which case, FIXED f 
j is assumed | 


L ____..__ ______ .__„_ 


A — — . . ____ _--._- 


.4 , 


_x .. -A—, . . - 


.1 __, .___,, „ ,_._ j 




T 


T 


j T 


_^» — __, .___,. _, — .__.. — .^ 


•srIFINED base- 


| level-one 




| 1 INI1, AUTO, RASED, 


| Defined nan.es always j 


• * K 1 ' 1 1 i* j r 


j variables 




| jcTL, STATIC, INT 


J have internal scope f 


j i i suw script-list] [ 






f j EXT, VAR, parameter 




- 1 pod ( integer) 1 > 










| DEF 










L _.___._____. . _. 


!____. _, — ._ 


.1. . ." __ 


_a . J. .. 


_i __, . 1 


r 


T 


T 


T T 


.j. _. . j 


j dimension 


[arrays, pararo- 






\ If lower bound is j 


( (bounds! , bounds! 


jeters Cimmedi- 






(omitted, 1 is assuired j 


| . . . ) where 


|ately following 








| • bounds* is 


{array name) 








| { [ lower : ] upper 1 | * 










j " 1 owe r " a nd 










|" upper" may be 










{element expres- 










1 sion for AUTO or 










JCTL; * only for 










|CTL or parameter, 










[with all or none 










( of bounds spec- 










ifications as 










fasterisks. For 










| parameter the 










} expression must be 










| an unsigned dec- 










j imal integer 










| constant . For 










J BASED, the last 










| upper may be 










I REFER 










j.. . — _____ 


[. __ ... 


| 


-A_. _ . _x ____ .. ._ 


X i 


i DIRECT 

i 

i 


RECORD files 


| EXCL 


Y ,^_ _. 

| FILF, RECORD, | STREAM, SECL, PR INT, 
|EXT,KEYEC |DUF,UNPUF # 
j j BACKWARD,", 


^_____._. ___________ ___J 

fSEQL is default for f 
(RECORD tiles j 


j._______._ _.. . — , 


________ . 


4 __ 


-X i 


_ a 


| ENTRY 


[entry points. 


{RETURNS, 


T _^. — _____ 


-j._._ ._ ___„ . __^ 


j [ (param-attr- 1 


entry parameters 


(GENERIC; 






| list £ , param- 




f Labels of 






| attr-listl...)) 




\ PROC or ENTRY j j 




I 




| statements 






1 




(and for con- 






I 




[textually de- 






1 




i clared entry 






I 




| names 






1- ._. — _. __ ._« 




y 


X , 1 . ,_____. 


L a 


1 ENVIRONMENT 


files 




T T " 


p _____________ . „| 

| PRINT files can get * j 


j (option-list) 








I ENV by default; all J 


j ENV 








| other files must have | 


j CSee "Options of j 
{the ENVIRONMENT 

{Attribute* at end | 

L ____ __. __J 




L ._. 


X t _ 


1 at least record forrr.at j 
(and blocksize speci- J 

| statement 1 
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r .. T « - T — T ■ T t " 

(Attribute and (Specified for (implied by or|I*piies or \ (Default 
(Abbreviation (Names of (Assumed for j An suited with (Conflicts with (Considerations 

j. x ___x +--,.~^ + + 

(EVENT (event variables (Undeclared ( ( (Default scope is INT; 
j (and parameters | identifiers ( j (default storaqe class 
( | | in LVKNT op- j j (is AUTO 
( ( ( tign or WAIT ( . ( ( 
j j (statement J j ( 

l x x + ^ x + 

(EXCLUSIVE (DIRECT UPDATE (Files impli- ( Fl^fi, RECORD, ( STREAK, SEQL, INPUT | 
(EXCL |files in a (citly opened | KEYgD,OUTPUT,( PRINT, ( 

i _, __ i , a . »«.-.-«;— —^•1.— .——-.———— .4 -.-.—— . --- .-i ■ — • 


| , , — ————.j,. , — — — — ^ „|.-„_ ,_-,—•»«>«-. f.—— — -----.—— ^ -— — — <r 

(EXTERNAL (level-one jfcntry names (STATIC ( INT, AUTO, BASED, (INT is default for all 
|EXT (variables with (of external ( (LEF,INIT with (names except those 
j (STATIC or CTL; (procedures, | (CALL option, (listed in column 3 

j j (defined con- ( j ( 
j j (dition names ( j | 

1 X _x x x— x 

(FILE | files, parame- (Any t ile-name( EXT | all but file-name ( 
j jters (*itt ribute; ( (and scope attri- ( 
j j (Undeclared ( jbutes | 
j | (identifier in( | ( 
( 1 (FILE option J I 1 
J ( | in I/O state- j j ( 
j ( (ment tor any j ( | 

l- X ... X _- -X .. X — X _ 

(FIXED (coded arithme- (Undeclared (" ( FLOAT, PIC (Defaults for partly 
j (tic variables | identifiers j ( (declared arithmetic 
( jand parameters (with initial ( ( (variables are REAL CEC 
| ( ( lett« i 1 ( ( (FLOAT unless scale 
j j (through N | j (factor appears in 
j ( {(applies alsoj j (precision attribute 
j j (to function | j (specification with a 
j ( (entry names) ( j (base or mode attribute 

| ( III (assumed 

H -_ X . — _+— — ... ^x — -„ X- . X 

(FLOAT (coded arithmet ic| Undeclared ( (FIXED, PIC (Defaults for partly 
j (variables, pata- | identit iers ( j (declared arithmetic 
( (meters (except those | j (variables are REAL DEC 
I j (with initial ( j (FLOAT unless scale 
j j | letters i ( j (factor appears in 
j ( j through N | | (precision attribute 
j ( |<ar-plies also( | (specification with a 
j j (to function | j (base or mode attri- 
j j (entry names) ( j jbute, in which case 
( ( ill (FIXED is assumed 

L — _- X — -X X . X X 

(GENERIC (f airily of entry j ( (any other attri- (A generic name is 
j C entry-name- (names ( j * jbute, including (always considered to 

J I, entry-name- ( ( t 1 (INT attributes, even 
\ decll - . . ) | | ( ( (if entry names of 
j | j 1,1 (family members have 
I | ( I ( (the EXT attribute 

i - - r i- - , r , m , - _- i -.. „r»r,-r ,. „. i ,- ■■«, - - I , «... , ,, u _ »- -u s- , m u, - ^1 


I T T ■"' f-' " I ■ t™ " - " " ~ ~ 

(INITIAL (problem data | ( | ENTRY, FILE, DEF, ( 
j <iteml,iteml (element and } | j BASED, PTR,OFTSET | 
j ...) (array variables ( ( j LABEL with STATIC, ( 
(INIT (or label var- j ( (parameter, J 
("item" is an (iables ( I (structure ( 
j arithmetic con- ( 111 I 
( stant or an | | ( ( ( 
(asterisk; repeti- | III | 
J tion factors may j ( ( j ( 
(appear with string j | ( j ( 
(constants, and | ( ( j I 
j iteration factors ( ( J j ( 
(may be specified | ( | j ( 
(for array | 1(1 ( 
(initialization j til | 
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| At t.i ibiit€! and 
| Abbr ev i.ai ion 


T - . •-« — . .-.- 

(Specified for 
(Names ot 


T — .--« — — T .—- . 

| implied Ly or| Implies or 
| Assumed for J Assuired wi 

A, .. ___ __._._ «. _«._, 


r h|Conf liotr. with 


- T _.— -_ . .- - 1 

(Default | 

(Considerations j 

X _ . __l 


( INITIAL CALL 
| Harq-list)] 
| INIT CALL 

L 


T --- - 

(same as iihovr 
(plus locator and 
(area variable:; 
x_ _ „ „ . _ 


JL — _ _ ___X_. — «.._.__, 


| ENTRY, FILE, STATIC | | 
(DEFEASED, parame-j j 
jter, structure j | 

__A _. ___ _ _ X _. . . J 


| INPUT 


| files 


fBACKWAHDSj {FILE, EXT 


— ^ — _ _. - 

| OUTPUT, UPDATE 


T T 

| INPUT is default f 


1 

1 




| Fi ies impii- | 
j citly opened | 


| EXCL, PRINT 


(for files ( 


! 
1 




| by HEAD or j 
JGE1 statement f 






i 










! 




| DATE has beenf 






1 

1 

j INTERNAL 

1 
1 


| level-one 


| explicitly | 

J specified) | 

| La tainet ers, j 

| iables, entry | 
j names of in- *f 


|EXT 


_X _.__ — _ _„_ H 

| INT is default for J 

(variables of any j 

( storaqe class j 
1 (including task and j 


I 
1 

| KEYED 
i 


| DIRECT and 

| SEQUENTIAL r ILfcil 


Jternal pro- f 
j cedures | 

| DIRECT, EXCL | FILE, EXT 


| STREAM, PRINT 
j BACK WAR Dr» 


(event variables) j 


r ~ 
| LABEL 


| label variables 


j Label { re- | 


jail other attri- 


t ~ "f 


| t (stirt - label" 

| constant 

| 1 1 stint-l«abel- 

| const)...)) 
(the list of con- 


[and paramet ers 


tixf:;, except | 
( those of PROC | 
,and FNTKY f 

i sta t ements j 


butes except 
[ALIGNED, scope an 
jstoraqe class 
j attributes, 


d| ( 


| stant specifies 
{ the ranqe of val- 










ues the variable 
jean have 










L _ _ __, 






i 




| length 


strmq variables 




"""t~ ""*" T - •"- ' "~1 

|any attributes not J j 


J Cexp | * | REFER- 


and parameter?; 




fallowed in a vn li 


dl 1 


I option) 
(must i mmediately 






(strinq declaration! | 


| follow CHAR or BIT 










l"exp" must be un- 
|siqned decimal 










{integer constant 










(rameter; asterisk 
j is allowed for CTL 










J or parameter; 










1 REFER option is 










fallowed for last 










| elementary name in 










J based structure 










j. .__. .j 








_X— — — I 


|LIKE struct-var j 


structure vari- 
ables 




|all data attri- 
1 butes 


— j— . — - -— .«{ 

(Note: attributes of j 


| "struct-var" can- 
j not itself have ! 

j been declared with] 
j the LIKE attributel 


(the structure name ( 

(itself do not carry | 
| over j 


j OFFSET (area-name) | 
j "area -name" must j 
| be level-one based) 
|area variable | 


oftset variables] 
and parameter | 




j PTR, INIT without 
j CALL option 


_^,«.._ _ . — „__ — .^ 
(Can cause contextual j 
(declaration of area j 
(name, but error will j 
(result because default j 


f 1 

1 ! 






_x 


(storage class will be j 
(AUTO, not BASED f 
X I 


} OUTPUT | 
1 1 
1 I 
I 1 
1 1 

1 i 
I 1 
1 I 
t I 


files | 


PRINT; | FILE, EXT 

Files impli- | 

citly opened | 

by a PUT, | 

WRITE, or LO-( 

CATE, state- j 

merit (unless f 

UPDATE has | 

been nx t r \i~ | 


(UPDATE, INPUT, EXCL 
| BACKWARDS 


-f _ ____. — _ — . — __. — . — ,_._| 
(INPUT is default for f 
(files j 


1 1 

1 ! 

L— — ____—_-_ __.A 


_. « . . X 


citly speci- | 
tied | 

_____ . J. 


-JL ._,_ 


_A . . i 
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.X— . ™„ .... J 


!«. — ..—.. — __•_.«._.. 
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-^......p-. 
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.^... ^ 


| PICTURE 


| pictured nuat- 








[any other arith- 




j • numeric- pic- spec' 


'(eric character 








metic attribute 




jthe specification 


{variables and 








(except REAL and 




|ia a string of 


| parameters 








(COMPLEX 




| numeric picture 














j specif ication 














| characters any of 














| which nay be pre- 














[ ceded by a paren- 
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1 repetition factor 
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-X........—...— ... 


.x.. ...... ....... 


.x~- .— -— .. 




.X— ... .......... ..... 
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|, ... — ... — , — — . 


.j. 


-f 


T """ "" • — — 




.^.— ... ...... .... ..... 


.^.-. --.-..— ..——.-.— .^ 


| PICTURE 


(pictured charae- 








(any other string 


















[PIC 


| variables and 












(the specification 


! parameters 












j is a string of 














j character-string 














f picture specif ica- | 












j tion characters. 














| any of which may 














jbe preceded by a 














j parenthesized 














f decimal integer 














{constant, which 














(is a repetition 














| factor. At least 














(one X or A must 














j appear 

i_ . ., ..... 


.x... ,. .. „, 


-X--— - .... — 


-X— -» 




.X ■ 


_X - — 4 


^— — .. 


..j... .. — — 


—J.--.. .. — ..... 


..^.. .*..... 




.f. .... ... 


.f... . .... . .. ^ 


| POINTER 


[pointer varia- 


| Any unde- 






[OFFSET, UN AL,INIT 




fPTR 


jbles parameters 

_x . ..... .. 


clared iden- 
[tifier that 
[appears in a 
[BASED attri- 
bute specif i- 
[ cation or in 
\a SET option 
| or as a 
[pointer qual 
j if ier 






[without CALL 




j._ . _ 


»^ — .. 


.f ....... — 


-f- — " 




-^. . 


.^.. . <f 


j POSITION 


[defined string 










(If POSITION is omitted j 


J Cinteger) 


[variables 










(in string defining, j 


|POS 


[(appears only inj 








[Por;(i> is assumed j 




| DEFINED attri- 














jbute specifica- 














1 1 i on) 

.x. ............ 


-x.~.- ....... 


-X— ....... 




_X ■ 






.f ... — 


-.j..... — ....... 


T * ~ 




-^ 




| precision 


J coded arithmetic [ 


( * 




[any attribute not 


[Default: ( 




[variables and 








[allowed for coded 




I Cp) 


[parameters 








(arithmetic vari- 


|C5,0) for DEC ( 


|"p" itiay be 


[immediately fol- 








ables 


| FIXED [ 


| element 


lowing the base 


» 1 








| (15,0) for BIN ( 


{expression for 


[scale, or mode 










| FIXJED [ 


|AUTO or CTL var- 


[attribute key- 










[ (6) for DEC [ 


fiables, otherwise 


[word 










( FLOAT [ 


J unsigned decimal 












[ (21) for BIN j 


| integer constant 


„X ......... 


~4 








( FLOAT J 
-4 I 




^ - — 




1 I 


1 *p»q> 


J fixed-point 








[same as atove. 




J either number 


(coded arith- 








(plus FLOAT 




j may be an element 


[metic variables 












| express! on for 


(and parameters. 












jAUTO or CTL varia- 


-[specified as 












jbles; "q* may 


[above 












[have negative 














| value 


-X— — .- ....... , 


_X.~.-.— -—.-—- 


-X— — 




.x • — 


-X— ..—.-— .- . ...... ...J 




..f — 


_,^.— .... ...... 


T — — <■»- — « 




J . .. ..... 


^ . .. _| 


| PRINT 


(STREAM OUTPUT 




(FILE, STREAK 


, j INPUT, RECORD, and 


[If no FILE or STREAM ( 




(files 




[OUTPUT,] 


FXT 


j record-oriented 
(file-name attri- 
1 butes 


(option appears in a j 
[PUT statement, j 

[SYSPRINT is assumed j 
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| Attribute 


and 
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1 lint lied by or 


| ln*|>i 


ies, or 


I , 




IDefault \ 


| Abbreviat ion 


| Names of 


| Assumed for 


j As s u pr ed * w i t h j C on f 1 i c t s with 




j Considerations f 
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±~. 




„x L . --- 
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T~ 




T 






fKEAL 
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| ment and array 

{variables, 
| parameters 

— X— — — -. — — -.— — — — .«._.. 


x «„_ 


| DEC , 

X-. . 


FLOAT 


f COMPLEX 
i 

1 

1 

„x. -«. . 




[REAL is default for | 
jail arithmetic j 

| variables j 






-• t- .- — •— *■• ,«-- 


^ 


T 




T 






| RECORD 




|files 


| UPDATE, BUF, 
jUNBUt ,SEgL, 
| DIRECT KEYED, 
| BACKWARDS, 

| in>i lici t ly 
| opened by 
[READ WRITE, 
I LOCATE, RE- 
(WR1TE, and 

| statements 


| FILE 


, EXT 


| STREAM, PRINT 

1 

1 

1 

1 

1 

I 

1 

1 

I 

1 

1 

-X- ,- 




fSTREAM is default | 

| for f lies J 


| RETURNSCattribute 


s)entry foints of 


[entry names 


| ENTRY 


T 

Jail but ent ry- 




| Defaults for returned | 


toniy arith 


roe tic. 


| function 


|of function 






[ name attributes 




lvalue are FIXED BIN | 


jstrinq, lo 


ca tor # . 


| procedures 


| | rocedures 






1 




( (15, 0) if initial | 


| a nd AREA a 


tt ri- 










1 




| letter of entry narre j 


| ibutes can 


te 










1 




j is I through N; other- } 


| speci i led 












I 

„X— ._ 




[wise, FLOAT DEC ( 6 ) [ 


! SEQUENTIAL 










, RECORD 






| *"»EyL 








EXT 




| DIRECT 

_4 . , _ _„ 




{RECORD files [ 


| STATIC 




f ievei-one 
I variables 


EX'l 






|AUTO, based, CTL, 
| parameter , €±<\ 7U: 
jable bounds ot 

j lengths or size: 


;t- 

* t 


| AUTO is default j 

| storage class unless | 
1 EXT is specif ied, in j 
Jwnich case, STATIC is \ 














| INIT *ith CALL or 


fassuned j 














| INIT with LABEL 

_jLL_' . 






(STREAM 




| files 


PRiNT; 

I" 1 It-S in. j li- 
cit iy opt n^ij 
by GET ot PUT 
st tit rment 


FILE, 


EX'l 


T 

JFiECORD, 

| reccbd-ot'ient ed 
j f i le-najfe 
| attributes 

1; ' ', 




jSTREAM is default j 
j for f lies | 


| UNALIGNED 




j element , array, 








(ALIGNED, PTR, LABEL, 


| Defaults are applied f 


|UNAL 




{structure vari- 
[abies, paraiie- 
jters 








[OFFSET", EVENT, TA; 

[AREA 

I 

1 

I 

1 

_X . -.„ 


K , 


|at elenr€>nt level: | 
jUNAL for bit, char- J 
Jacter, pictured ddtd; J 
[ALIGNED tor all cth-r | 

[data types; constants | 
[take tie faults | 


| UNBUFFERED 




j TRANSIENT and 




FILE, 


RE CURL 


^ — — «. _. 

[ BUF, ST REAM, PR INI 




[ BUF is ietault for | 


|UNBUF 




ISE^L tiles f 




EXT 




J DIRECT, LXCL 




| RECORD tiles [ 


| UPDATE 




| RECORD tiles 
-X- .-.- - _ i 


LXCL; 

b iles iui| 1 i- | 
ci t 1 y opened 
iy <i REWRITE | 
ur DEDnlE 
statemt-nt | 


FILE, 

EXT 


RECORD 


. j. _ _ _ - _ _ _ „ _ 
| INPUT, OUT1 UT, 
[STREAM, PRINT, 
| BACKWARD.; 
1 
1 
1 

-X- --- - - 




t INPUT is default for | 
[tiles [ 






T T 








T 




|_ . -.-. — __ .--___. .^ 


[VARYING 




(strintj element j 








|Mc 






| VAR 




| and a i ray Vdr- | 
{ lables and pa- \ 
jraroeters speci- | 
| f ied on Jy in | 
(conjunction witnj 








t 
1 
1 
1 
1 
1 







Options of the Environment Attribute 
F (block-si ze ( , recoid-s ize J > | 

VCmax- block- s ize ( , record-size J ) j 
{VSjVBS} Cmax-biock-size J record 
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SECTION 10: STATEMENTS 



This section presents the PL/I state- 
ments in alphabetical order. (The prepro- 
cessor statements are alphabetically 
arranged at the end of this section.) Most* 
statements are accompanied by the following 
informations 

1. Function — a short description of the 
meaning and use of the statement 



2. General format 
statement 



the syntax of the 



3. Syntax rules — rules of syntax that 
are not reflected in the general 

format 

4. General rules — rules governing the 
use of the statement and its meaning 
in a PL/I program 



The ALLOCATE Statement 

Function: 

The ALLOCATE statement causes storage to 
be allocated for specified controlled or 
based data. 

General format: 

Option 1: 

ALLOCATE ( level! identifier 
(dimension! tattributel . . . 
(, [level) identifier [dimension! 
[attribute! ...!••.; 

Option 2: 

ALLOCATE based- variable- identifier 
[SET (pointer-variable)! 
[IN C area-variable)! 
[ , based-variable-identifier 
[SET Cpointer-variable) ! 
[IN (area-variable) !!...; 

Syntax rules: 

1. Based variables and controlled 
variables may both be specified as 
identifiers in the same ALLOCATE 
statement. 

Syntax rules 2 through 7 apply only to 
Option 1: 

2. "Level - indicates a level number. The 
first identifier appearing after the 
keyword ALLOCATE must be a level 1 
identifier. 



Each identifier must represent data of 
the controlled storage class or be an 
element of a controlled major 
structure. 



4. "Dimension" indicates a dimension 
attribute. "Attribute" indicates a 
BIT, CHARACTER, or INITIAL attribute. 

5. A dimension attribute, if present, 
must specify the same number of dimen- 
sions as that declared for the asso- 
ciated identifier. 

6. The attribute BIT may appear only with 
a BIT identifier; CHARACTER may appear 
only with a CHARACTER identifier. 

7. A structure element name, other than 
the major structure name, may appear 
only if the relative structuring of 
the entire structure appears as in the 
DECLARE statement for that structure. 

Syntax rules 8 and 9 apply only to 
Option 2: 

8. The based variable appearing in the 
ALLOCATE statement may be an element 
variable, an array, or a major struc- 
ture. When it is a major structure, 
only the major structure name is 
specified. 

9. The SET clause, if present, may appear 
preceding or following the IN clause. 

General rules: 

Rules 1 through 6 apply only to Option li 

1. When Option 1 is used, an ALLOCATE 
statement for an identifier for which 
storage was allocated and not freed 
causes storage for the identifier to 
be "pushed down" or stacked. This 
pushing down creates a new generation 
of data for the identifier. When 
storage for this identifier is freed, 
using the FREE statement, storage is 
"popped up" or removed from the stack. 

2. Bounds for arrays, lengths of strings, 
and sizes of areas are fixed at the 
execution of an ALLOCATE statement. 

a. If a bound, length, or size is ex- 
plicitly specified in an ALLOCATE 
statement, it overrides any bound, 
length, or size given in the 
DECLARE statement. 
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b. If a bound, length, or size is 
specified by an asterisk in an 
ALLOCATE statement, that value is 
taken from the current generation. 
If no generation of the variable 
exists r the bound, length, or size 
is undefined. 

c. Either the ALLOCATE statement or 
the DECLARE statement must specify 
any necessary dimension, size, or 
length attributes for an identifi- 
er* Any expression taken from the 
DECLARE statement is evaluated at 
the point of allocation using the 
condition enabling of the ALLOCATE 
statement, although the names are 
interpreted in the environment of 
the DECLARE statement. 

d. If, in either an ALLOCATE or a 
DECLARE statement , bounds, 
lengths , or area sizes are speci- 
fied by expressions that contain 
references to the variable being 
allocated, the expression are eva- 
luated using the value of the most 
recent generation of the variable. 

3. Upon allocation of an identifier, ini- 
tial values are assigned to it if the 
identifier has an INITIAL attribute in 
either the ALLOCATE statement or 
DECLARE statement. Expressions or a 
CALL option in the INITIAL attribute 
are executed at the point of alloca- 
tion, using the condition enabling of 
the ALLOCATE statement, although the 
names are interpreted in the environ- 
ment of the declaration. If an INI- 
TIAL attribute appears in both DECLARE 
and ALLOCATE statements, the INITIAL 
attribute in the ALLOCATE statement is 
used. If initialization involves 
reference to the variable being allo- 
cated, the reference will be to the 
new generation of the variable. 

4. To determine whether or not storage 
has been allocated for an identifier 
the built-in function ALLOCATION may 
be used. 

5. A parameter that is declared CON- 
TROLLED may be specified in an ALLO- 
CATE statement. 

6. Any evaluations performed at the time 
the ALLOCATE statement is executed 
(e.g., evaluation of expressions in an 
INITIAL attribute) must not be inter- 
dependent i they cannot depend on each 
other at the same time. 

Rules 7 through 12 apply only to Option 



7. When Option 2 is used, storage is not 
^pushed down" or stacked. In this 
case, reference may be made to any 

generation of a based variable through 
a pointer variable. 



8. The SET clause indicates the pointer 
variable that is to receive the value 
identifying the allocation. The SET 

clause need not name the pointer vari- 
able declared with the based variable. 
If the SET clause is omitted, the 
pointer that was declared with the 
based variable is set. 

9. If the IN clause appears in the ALLO- 
CATE statement, storage will be allo- 
cated in the named area, for the based 
variable. If sufficient storage does 
not exist within this area, the AREA 
condition will be raised. 

10. The amount of storage allocated for a 
based variable depends on its attri- 
butes, and on its dimensions and 

length specifications if these are 
applicable at the time of allocation. 
These attributes are determined from 
the declaration of the based variable, 
and additional attributes may not be 
specified in the ALLOCATE statement. 
A based structure may contain one 
adjustable array bound or string 
length, whose value is taken, on allo- 
cation, from the current value of a 
variable outside the structure Csee 
•The REFER Option 81 , in Part I, Section 
14, "Based Variables and List Proces- 
sing. •> Note that the asterisk nota- 
tion for bounds and length is not per- 
mitted for based variables. 

11. If the area variable is an array, the 
subscripts must be specified with the 
area variable, 

12. A based variable transferred as an 

argument to a procedure cannot appear 

in an ALLOCATE statement in the called 
procedure. 

Examples ? 

1. The following examples illustrate the 
use of the ALLOCATE statement for a 
controlled identifier; 

DECLARE ACN1,N2) CONTROLLED 3 



Nl, N2 = 10? 
ALLOCATE A; 

ALLOCATE A 

CK1,K2); 



The bounds are 10 and 

10 
The bounds are Kl and 

K2 which override Nl 

and N2« 
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Nl = Nl + 1; 

ALLOCATE A; 

ALLOCATE A 

ALLOCATE A 

(Jl, J2); 



The bounds are 11 and 
10. 

The bounds are 11 and 

1G. 
The bounds are Jl and 

J2. 



2. The following example illustrates the 
use of the ALLOCATE statement when the 
DECLARE statement contains asterisks 
for the length of a controlled bit 
string B: 

DECLARE B BIT (*) VARYING CONTROLLED ; 



ALLOCATE B 

BIT (*) ; 
ALLOCATE B; 

ALLOCATE B 

BIT (N) ; 
ALLOCATE B CHAR- 
ACTER UK- 
ALLOCATE B 

BIT (8); 



Invalid; violates rule 
2b. 

Invalid; violates rule 
2b. 

The maximum length is 
N. 

Invalid; violates syn- 
tax rule S. 

The max imam length is 
8. 



3. The following example illustrates the 
use of the built-in function ALLOCA- 
TION and of the INITIAL attribute for 
a controlled variable in an ALLOCATE 
statement: 

DECLARE A(N,N) CONTROLLED INITIAL 

( (N*N)G) ; 



IF -, ALLOCATION (A) THEN AILOCATE A 
INITIAL (1,(N-1) <(N)0,D); 



cular allocat ir,u The n: ■*,'< 
value of N is ut <u to -.ic-'i i-mhiv.. ■ 
the bound of VALUES, ani Mils 
value is assigned to DIM 

C. ALLOCATE RATES SET (T> iN TAPJ.K; 
Allocates storage within the atva 
S-> TABIE for the variable RATES. 
The pointer variable T is s el to 
identify the location within TABLE 
at which RATES is allocated. 

The Assignment State ment 

Function: 

The assignment statement is used t...< 
evaluate an expression and to assign i?.s 
value to one or more target variables; the 
target variables may be element, array? or 
structure variables. The target variables 
may be indicated by pseudo-variables. 

General formats: 

The assignment statement has three gen- 
eral format options. They are given in 
Figure U9 . 

Syntax rules : 

1. In Option 2, each target variable must 
be an array. If the right-hand side 
contains arrays of structures, then 
all target variables must be arrays of 
structures. The BY NAME option may be 
given only when the right-hand side 
contains at least one structure, 

2. In Option 3, each target variable nast 
be a structure. 



General rules: 



ALLOCATE A; 

4. The following example illustrates 

three uses of Option 2 of the ALLOCATE 
statement for based identifiers. 

DECLARE VALUE BASED (P), 

RATES BASED (Q) 

1 GROUP BASED (R) , 
2 DIM FIXED BINARY, 
2 VALUES (N REFER (DIN)), 

TABLE AREA BASED (S) f 

N FIXED BINARY, 

T POINTER; 

a. ALLOCATE VALUE SET (P) ; 
Allocates storage for the based 
variable VALUE and sets the point- 
er variable P to identify the par- 
ticular allocation. 

b. ALLOCATE GROUP SET (R) ; 
Allocates storage for the struc- 
ture GROUP, and sets the pointer 
variable R to identify the parti- 



Aggregate assignments (Options 2 and 
3) are expanded into a series of ele- 
ment assignments according to rules 5 
through 8. 

An element assignment is per termed as 
follows : 

a. Subscripts of the target 
variables, and the second and 
third arguments of SUBSTR pseucic- 
variable references, are evaluated 
from left to right. 

b. The expression o», the right-hand 
side is then evaluated. 

c. For each target variable (in left 
to right order), the expression is 
converted to the characteristics 
of the target variable according 
to rules for data conversion 
(except that whenever a conversion 

of arithmetic base is involved, 
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(Option 1 (Element Assignment) 



element-variable 



, element- variable! 



pseudo-variable j , pseudo-variable 
(Option 2 (Array Assignment) 



array-variable 
pseudo-variable 



t array-variable 
, pseudo-variable 



(Option 3 (Structure Assignment) 



structure-variable [ , structure-variable] 



. = eleirent-expression; 



structure-expression [ , BY NAME] 
array-expression [ # BY NAME] 
elenrent-expression 



structure-expression [ , BY NAME] 
element-expression 



Figure 49. General Formats of the Assignment Statement 



the value is converted directly to 
the precision of the target vari- 
able). The converted value is 
then assigned to the target 
variable. 

For the TSS/360 compiler, multiple 
assignments are limited by the follow- 
ing rule: 

Count 11 for each target of a multiple 
assignment, add 3 for each pseudo- 
variable, and then add 11 for each 
argument of a pseudo-variable. The 
total must not exceed 4,085. 

The following rules apply to string 
element assignment: 

a. The assignment is performed from 
left to right, starting with the 
leftmost position. 

b. If the target variable is a fixed- 
length string, the expression 
value is truncated on the right if 
it is too long or padded on the 
right (with blanks for character 
string, zeros for bit strings) if 
the value is too short. (Note 
that a string pseudo-variable is 
considered to be a fixed-length 
string). The resulting value is 
assigned to the target. 

c. If the target is a VARYING string 
and the value of the expression is 
longer than the maximum length 
declared for the variable, the 
value is truncated on the right. 
The target string obtains a cur- 
rent length equal to its maximum 
length. If the value of the 
expression is not longer than the 
maximum length, the value is 
assigned? the target string 



obtains a current length equal to 
the length of the value. 

The following rules apply to other 
element assignments: 

a. If the target is an area variable, 
the expression must be an area 
variable or function. The AREA 
condition will be raised by this 
assignment if the size of the tar- 
get area is insufficient for the 
current extent of the area being 
assigned. 

b. If the target is a pointer vari- 
able, the expression can only be a 
pointer (or offset) variable or a 
pointer (or offset) function 
reference. If the expression is 
of offset type, its value is con- 
verted to pointer. 

c. If the target is an offset vari- 
able, the expression can only be 
an offset (or pointer) variable or 
an offset (or pointer) function 
reference. If the expression is 
of pointer type, its value is con- 
verted to offset. 

d. If the target is a label variable, 
the expression can only be a label 
variable or label constant. 

Environmental information (i.e., 
information that identifies the 
invocation of the block) is always 
assigned to the label variable. 

e. If the target is an event vari- 
able, the expression can only be 
an event variable. The assignment 
is uninterruptable, and it 
involves both the completion and 
status values. An event variable 
does not become active when it 
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has an active event variable 

assigned to it. It. is an error to 

assign to an active event 
variable. 

f. If the target is a STATUS pseudo- 
variable, a value can oe assigned 

whether or not the event variable 
is active. It is an error to 
assign to a COMPLETION pseudo- 
variable if the named event vari- 
able is active* 

The first target variable in an 
aggregate assignment is known as the 
roaster variable . If the roaster vari- 
able is an array, then an array expan- 
sion (Rule 6) is performed; otherwise, 
a structure expansion ( Rules 7 and 8) 
is performed. The CHECK condition for 
assignment, to a target variable is not 
raised during the assignment; it is 
raised (when suitably enabled) after 
the assignment is complete. Such 
CHECK conditions are raised in the 
written order of the enabled identi- 
fiers. In the case of BY NAME assign- 
ments tne CHECK condition for the tar- 
get variable is raised regardless of 
whether any value is assigned to an 
item. The label prefix of the origi- 
nal statement is applied to a null 
statement preceding the other 
generated statements. 

In Option 2, all array operands must 
have the same number of dimensions and 
identical bounds. The array assign- 
ment is expanded into a loop of the 

form: 



assignment statement (which may have 
been generated by Rule 7 or Rule 8) 
has a condition prefix, the generated 
assignment statement is given this 
condition prefix. If the original as- 
signment statement (which may have 
been generated by Rule 8) has a BY 
NAME option , the generated assignment 
statement is given a BY NAME option. 
If the generated assignment statement 
is a structure assignment, it is 
expanded as given below. 

In Option 3, where the BY NAME option 
is not specified, the following rules 

apply: 

a. None of the operands can be 
arrays, although they may be 
structures that contain arrays. 

b. All of the structure operands must 
have the same number, k, of imme- 
diately contained items. 

c. The assignment statement (which 
may have been generated by Rule 6) 
is replaced by k generated assign- 
ment statements. The ith 
generated assignment statement is 
derived from the original assign- 
ment statement by replacing each 
structure operand by its ith con- 
tained item; such generated as- 
signment statements may require 
further expansion according to 
Rule 6 or Rule 7. All generated 
assignment statements are given 
the condition prefix of the origi- 
nal statement. 



LABEL: DO ji 



LBQUND(master-variatle, 1 ) TO 
HBOUND (master-variable, 1) ; 



DC j2 = LBOUND<iraster-variable,2) TO 
HBOUND (master-variable, 2) ; 



9. In Option 3, where the BY NAME option 
is given, the structure assignment, 
which may have been generated by Rule 
6, is expanded according to steps (a) 
through (d) below. None of the 
operands can be arrays. 



DO jn = LBOUND(master-variable,n> TO 
HBOUND (master-variable, n) ; 



a. The first item immediately con- 
tained in the master variable is 
considered. 



generated assignment statement 

END ISABEL; 

In this expansion, n is the number 
of dimensions of the master variable 
that are to participate in the assign- 
ment. In the generated assignment 
statement, all array operands are 
fully subscripted, using (from left to 
right) the dummy variables jl to jn. 
If an array operand appears with no 
subscripts, it will only have the sub- 
scripts jl to jn; if cross-section 
notation is used, the asterisks are 
replaced by jl to jn. If the original 



b. If each structure operand and tar- 
get variable has an immediately 
contained item with the same iden- 
tifier, an assignment statement is 
generated as follows: the state- 
ment is derived by replacing each 
structure operand and target vari- 
able with its immediately con- 
tained item that has this identi- 
fier. If any structure contains 
no such identifier, no statement 
is generated. If the generated 
assignment is a structure or 
array-of-structures assignment, BY 
NAME is appended. The first 
generated assignment is given the 
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a. 



label prefix of the original as- 
signment statement; all generated 
assignment statements are given 
the condition prefix of the origi- 
nal assignment statement. 



Step b is repeated for each of the 
items immediately contained in the 
master variable. The assignments 
are generated in the order of the 
items contained in the master 
variable. 

Steps a through c may generate 
further array and structure assig- 
nments. These are expanded 
according to Rules 6 through 8. 



Examples : 



Suppose that the following three 
structures have been declared. 



1 ONE 



1 TWO 



PARTI 

3 RED 

3 GREEN 

3 WHITE 

PART2 

3 BLUE 

3 YELLOW 

3 ORANGE (3) 



PARTI 

3 RED 

3 WHITE 

3 BLUE 

PART 2 

3 GREEN 

3 YELLOW 

3 ORANGE (3) 

PART3 

3 BLACK 

3 WHITE 



1 THREE 
3 PARTI 
5 BLACK 
5 WHITE 
5 RED 
3 PART2 
5 YELLOW 
5 WHITE 
5 0RANGE(3) 
5 PURPLE 

Consider the following assignment: 

ONE = TWO - 2 * THREE, BY NAME? 

By Rule 8 this generates: 

ONE. PARTI = TWO. PARTI - 2 * 
THREE. PARTl r BY NAME; 

ONE.PART2 = TWO.PART2 - 2 * 
THREE. PART2, BY NAME; 

Applying Rule 8 again, these state- 
ments are replaced ty : 

ONE . PARTI . RED = TWO . PARTI . RED 

- 2 * THREE. PARTI. RED; 

ONE. PARTI. WHITE = TWO. PARTI .WHITE 

- 2 * THREE. PARTI. WHITER- 



ONE. PART 2. YELLOW = TWO. PART2. YELLOW 

- 2 * THREE. PART2- YELLOW ; 

ONE. PART2. ORANGE = TWO. PART2 .ORANGE 

- 2 * THREE. PART2. ORANGE; 

The final assignment is expanded 
according to Rule 6. 

2. The following example illustrates 
array assignment (Option 2) : 



Given the array A 



and the array B 



2 
3 
1 

a 
i 

7 
3 

6 



4 
6 
7 
8 

5 
8 

a 

3 



Consider the assignment statement: 

A = (A+B)**2-A(l,l); 

After execution, A has the value 

7 m 
93 189 

9 114 
93 114 

Note that the new value for A (1,1), 
which is 7, is used in evaluating the 
expression for all other elements. 

3. The following example illustrates str- 
ing assignment: 

Given: 

A is a fixed-length string whose 

value is 'XZ/BQ 1 . 
B is a varying-length string of 

maximum length 8 whose value is 

•MAFY*. 
C is a fixed-length string of 

length 3. 
D is a varying-length string of 

maximum length 5. 

Then in the statement: 

C=A, the value of C is • XZ/*. 

C= , X f , the value of C is 'Xbb' . 
D=B, the value of D is ■ MAFY f . 
D=SUBSTR(A, 2, 3) | (SUBSTRCA, 2,3) , 

the value of D is ■ Z/BZ/'. 
SUBSTRCA, 2, 4)=B, the value of A is 

•XMAFY' . 
SUBSTRCB, 2,2) = ^' , the value of B 

is •MRbY'. 
SUBSTR(B,2)= , R' , the value of B is 

1 MRbb • . 

The BEGIN Statement 
Function: 
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The BEGIN statement heads and identifies 

a begin block. 

General tormat: 

BEGIN [ORDER IREORTER] ; 

Syntax rules: 

1. A label of a BEGIN statement may be 
subscripted, but such a label cannot 
appear after an END statement. 

General rules: 

1. A BEGIN statement is used in conjunc- 
tion with an END statement to delimit 
a begin block, A complete discussion 
of begin blocks can be found in Part 
I, Section 6, "Blocks, Flow of Con- 
trol, and storage Allocation." 

2. The ORDER option specifies that the 
normal language rules are not to be 
relaxed; i.e., any optimization must 
be such that the execution of a jolock 
always produces a result that is in 
accordance with the strict definition 
of PL/I. This means that the values 
of variables set by execution of all 
statements prior to computational or 
system-action interruptions are 
guaranteed in an on-unit entered as a 
result of the interruption, or any- 
where in the program afterwards. Note 
that the strict definition now allows 
the compiler to optimize common expre- 
ssions (see note below), where safely 
possible, by evaluating for each 
reference. 

Note : A common expression is an 
expression that occurs more than once 
in a program but is obviously intended 
to result in the same value each time 
that it is evaluated, i.e., if a later 
expression is identical to an earlier 
expression, with no intervening modi- 
fication to an operand, the expre- 
ssions are said to be common. 



3. 



The REORDER option specifies that 
execution of the BEGIN block must pro- 
duce a result that is in accordance 
with the strict definition of PL/I 
unless a computational or system- 
action interruption occurs during 
execution of the block? the result is 
then allowed to deviate as follows: 

a. After a computational or system- 
action interruption has occurred 
during execution of the block, the 
values of variables modified, 
allocated, or freed in the bloc's 
are guaranteed only after normal 
return from an on-unit or when 
accessed by the ONCHAR and 



ONSOURCE condition built-in 
functions. 

b. The values of variables modified, 
allocated, or freed in an on-unit 
for a computational or system- 
action condition Cor in a block 
activated by such an on-unit) are 
not guaranteed on return from the 
on-unit into the block, except for 
values modified by the ONCHAR and 
ONSOURCE pseudo variables. 

A program is in error if a computa- 
tional or system-action interruption 
occurs during execution of the block 
and this interruption is followed by a 
reference to a variable whose value is 
not guaranteed in such circumstances. 
(See also Part I, Section 17: "Opti- 
mization and Efficient Performance.") 



The CALL Statement 

Function: 

The CALL statement invokes a procedure 
and causes control to be transferred to a 
specified entry point of the procedure. 

General format: 

CALL entry-name 

t (argument (, argument! • . . )J 
Syntax rules: 

1. The entry name, which can be a generic 
name, represents the entry point of 
the procedure invoked. 

2. An argument cannot be a condition 
name. 

General rule: 

See Part I, Section 12, "Subroutines and 
Functions" for detailed descriptions of the 
interaction of arguments with the parame- 
ters that represent these arguments in the 
invoked procedure. 

txamj; les : 

1. CALL CRITICAL_PATH (A,B*C,D); 



CRITICAL PATH: PROCEDURE (ALP HA, BET A, 
GAMWA) ; 



END; 
2. CALL PAYROLL (NAME, DATE, HRRATE) ; 
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The CLOSE Statement 



Th'e DECLARE Statement 



Function: 



Function: 



The CLOSE statement dissociates the 
named file from the data set with which it 
was associated by opening in the current 

task* 



The DECLARE statement is the principal 
irethod for explicitly declaring attributes 
of names. 



General format: 

CLOSE FILE C file-name) I, FILE 
(file- name) 1 . - . ; 

General rules: 

1* The FILE (filename) option specifies 
which file is to be closed. It must 
appear once. Several files can be 
closed by one CLOSE statement. 

2* ft closed file can be reopened, 

3* .losing an unopened file r or an al- 
ready closed file, has no effect. 

4. The CLOSE statement cannot be used to 
close a file in a task different from 

the one that opened the file. 

5. If a file is not closed ty a CLOSE 
statement, it is automatically closed 
at the completion of the task in which 

it was opened. 

6 . All I/O events that have not been com- 
pleted before the file is closed are 

set complete, with a status value of 
1. 

7* A CLOSE statement unlocks all records 

in the file previously locked in the 
task in which the CLOSE appears. 

Examples: 

1. CLOSE FILE (MASTER); 

The file, MASTER, is closed, and the 
facilities allocated to it are 
released, 

2, CLOSE FILE CTABLEA) , FILE (TABLEB) ; 

The two files, TABLEA and TABLEB are 
closed in the same way as MASTER, in 

the preceding example. 



General format; 



DECLARE 

(level! identifier [attribute]... 

[ f [level] identifier [attribute) ...]...; 



Syntax rules : 

1. Any number of identifiers may be 
.declared in one DECLARE statement. 

2. "Level* is a nonzero unsigned decimal 
integer constant. If a level number 
is not specified, level 1 is assumed 
for all element and array variables. 
Level 1 must be specified for all 
major structure names. A blank space 
must separate a level number from the 
identifier following it. 

3. In general, attributes must immediate- 
ly follow the identifier to which they 
apply as shown in the general format. 
However, attributes can be factored 

(see "Factoring of Attributes" in Part 

II, Section 9, "Attributes"). 

General rules: 

1. A particular level 1 identifier can be 
specified in only one DECLARE state- 
ment within a particular block. All 
attributes given explicitly for that 

identifier must be declared together 

in that DECLARE statement. (Note, 
however, that identifiers having the 
FILE attribute may be given attributes 
in an OPEN statement as well. See 
"The OPEN Statement" in this section 
and in Part I, Section 8, "input and 
Output," for further information.) 

2. Attributes of external names, in 
separate blocks and compilations, must 
be consistent. 
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3. Labels may be prefixed to DECLARE 

statements (however, such labels are 
treated as comments and, hence, have 
no meaning) . Condition prefixes can- 
not be attached to a DECLARE statement. 

The DELAY Statement 

Function: 

The DELAY statement causes the execution 
of a task to be suspended for a specified 
period of time. 

General format: 

DELAY (element-expression) ? 

General rule: 

Execution of the DELAY statement causes 
the element expression to be evaluated and 
converted to an integer n; execution is 
then suspended for n milliseconds. 

Example: 

DELAY (10) ; 

This statement causes execution of the 
task to be suspended for ten milliseconds. 

The DELETE Statement 

Function: 

The DELETE statement deletes a record 
from an UPDATE file. 

General format: 



When control reaches a DELETE state- 
ment containing this option, the 
"event variable" is made active (that 
is, it cannot be associated with 
another event) and is given the com- 
pletion value 'O'B, provided that the 
UNDEFINEDFILE condition is not raised 
by an implicit file opening (see 
"Note" below) . The event variable 
remains active and retains its 'O'B 
completion value until control reaches 
a WAIT statement specifying that event 
variable. At this time, either of the 
following can occur: 

a. If the DELETE statement has been 
executed successfully and neither 
of the conditions TRANSMIT or KEY 
has been raised as a result cf the 
DELETE, the event variable is set 
complete, given the completion 
value "l'B, and the event variable 
is made inactive, that is, can be 
associated with another event. 

b. If the DELETE statement has 
resulted in the raising of TRANS- 
MIT or KEY, the interruption for 
each of these conditions dees net 
occur until the WAIT is encoun- 
tered. At such time, the corre- 
sponding on-units (if any) are 
entered in the order in which the 
conditions were raised. After a 
return from the final on-unit, or 
if one of the on-units is ter- 
minated by a GO TO statement, the 
event variable is given the com- 
pletion value ' 1'B and is made 
inactive. 



DELETE FILE (file-name) 
[KEY (expression) ] 
( EVENT ( event- variabl e) 1 ; 

General rules: 

1. The options may appear in any order. 

2. The FILE (filename) option specifies 
the UPDATE file; it must be specified. 

3. The KEY option must be specified if 
the file is a DIRECT UPDATE file,- it 
cannot be specified otherwise. The 
expression is converted to a character 
string and determines which record is 
to be deleted. 

**. If the file is a SEQUENTIAL UPDATE 

file, the record to be deleted is the 
last record that was read; the data 
set organization roust be INDEXED. 

5. The EVENT option allows processing to 
continue while a record is being 
deleted. This option cannot be speci- 
fied for a SEQUENTIAL BUFFERED file. 



7. 



Note : If the DELETE statement causes 
an implicit file opening that results 
in the raising of UNDEFINEDFILE, the 
on-unit associated with this condition 
is entered immediately and the event 
variable remains unchanged; that is, 
the event variable remains inactive 
and retains the same value it had when 
the DELETE was encountered. If the 
on-unit does not correct the condi- 
tion, then, upon normal return from 
the on-unit, the ERROR condition is 
raised; if the condition is corrected 
in the on-unit, that is,,if the file 
is opened successfully, then, upon 
normal return from the on-unit, the 
event variable is set to 'O'B, it is 
made active, and execution of the 
DELETE statement continues. 

The DELETE statement unlocks a record 
only if that record had been locked in 
the same task in which the DELETE 
appears. 

The DELETE statement can cause impli- 
cit opening of a file. 
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Example: 

DELETE FILE(ALPHA) KEY (DKEY) ; 

This statement causes the record identi- 
fied by DKEY to be deleted from the data 
set associated with the file ALPHA. If the 
record was previously locked in the same 
task, it is unlocked. 

The DISPLAY Statement 

Function: 

Tiie DISPLAY statement causes a message 
to be displayed at the user's terminal. A 
.response may be requested. 

General format: 

Option 1. 

DISPLAY (element-expression) ; 

Option 2. 

DISPLAY (element-expression) 
PvEPLY (character-variable) 
I EVENT (event-variable) 1 ; 

General rules: 

1. Execution of the DISPLAY statement 
causes the element expression to be 
evaluated and, where necessary, con- 
verted to a varying character string 
of implementation-defined maximum 
length (126 characters) . This 
character string is the message to be 
displayed. 

2. In Option 2, the character variable 
receives a string that is a message to 
be supplied by the user. The message 
cannot exceed 126 characters. 

3. In Option 2, if the EVENT option is 
not specified, execution of the pro- 
gram is suspended until the reply mes- 



sage is received. In option 1, execu- 
tion continues uninterrupted. 



4. If the EVENT (event-variable) option 
is given, TSS/360 execution waits for 
the reply to be completed before con- 
tinuing with subsequent statements. 
The completion part of the event vari- 
able will be given the value '0 f B 
until the reply is completed, when it 
will be given the value 'l'B. The 
reply is considered complete only 
after the execution of a WAIT state- 
ment naming the event. 



5. The EVENT and REPLY options can be 
given in either order. 

Example: 

DISPLAY ( • END OF JOB' ) ; 

This statement causes the message "END 
OF JOB" to be displayed. 

The DO Statement 

Function: 

The DO statement heads a DO-group and 
can also be used to specify repetitive 
execution of the statements within the 
group. 

General formats: 

The three format types for the DO state- 
ment are shown in Figure 50. 

Syntax rules : 

1. In all three types, the DO statement 
is used in conjunction with the END 
statement to delimit a DO-group, Only 
Type 1 does not provide for the repe- 
titive execution of the statements 
within the group. 



j Type 1. DO; 

[ Type 2. DO WHILE ( element- expression) ; 
i pseudo- variable 



[ Type 3. DO 



=specif ication [ , specification) . 



I variable 
where "specification" has the form: 

"TO expression2 (BY expression3] 
_BY expressions (TO expression21. 
Figure 50. General Format of the DO Statement 



expression! 



[WHILE (expressions ) 3 



L „ . , . 



J 
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6. 



In Type 3, the variable or pseudo- 
variable must represent a single ele- 
ment; "variable" may be subscripted 
and/or qualified. Peal arithmetic 
variables are generally used, but 
label, string, and complex variables 
are allowed, provided that the expan- 
sions given in the general rules below 
result in valid PL/I programs. Note, 
however, that if "variable" is a label 
variable, each "specification" must 
have the following form: 

I element-label- variable | 
label-constant J 

[WHILE (expression) ] 



Each expression in a specification 
must be an element expression. 



If "BY expression3" is omitted from a 
"specification," and if "TO expre- 
ssion2" is included, "expression3" is 
assumed to be 1. 



If "TO expression2" is omitted from a 
"specification," repetitive execution 
continues until it is terminated by 
the WHILE clause or by some statement 
within the group. 



If both "TO expression2" and "BY 
express ion3" are omitted from a speci- 
fication, it implies a single execu- 
tion of the group, with the control 
variable having the value of "expre- 
ssionl". If "WHILE expression**" is 
included, this single execution will 
not take place unless " expression^" is 
true. 



General rules: 



In Type 1, the DO statement only de- 
limits the start of a DO-group; it 
does not provide for repetitive 
execution. 

In Type 2, the DO statement delimits 
the start of a DO-group and provides 
for repetitive execution as defined by 
the following: 

LABEL: DO WHILE (expression) ; 
statement-1 



statement~n 
END; 
NEXT: statement /+STATEMENT 

FOLLOWING THE DO GROUP*/ 



The above is exactly equivalent to the 
following expansion: 

LABEL: IF (expression) THEN; ELSE 
GC TO NEXT; 
statement-1 



statement-n 
GO TO LABEL; 
NEXT: statement /*STATEMENT 

FOLLOWING THE DO GROUP*/ 

In Type 3, the DO statement delimits 
the start of a DO-group and provides 
for controlled repetitive execution as 
defined by the following: 

LABEL: DO variable (a ± , . . . , a n ) = 

express ionl 
TO expression2 

BY expression3 
WHILE (expressions) ; 
statement-1 



statement-m 
LABEL1: END; 
NEXT: statement 

This is exactly equivalent to the fol- 
lowing expansion: 

LABEL: temp i =a ± ; 



temp n =a n ; 
el=expressionl; 
e 2= express ion 2; 
e3=expression3 ; 
v=el; 
LABEL2: IF (e3>=0) & (v>e2) | 
(e3<0U(v<e2) 
THEN GO TO NEXT; 
IF (expression^) THEN; 

ELSE GO TO NEXT; 
statement-1 



LABEL1 : 



NEXT: 



statement-m 

v=v+e3; 

GO TO LABEL2; 

statement 



In the above expansion 
expressions that may a 
scripts of the control 
tempi . • .temp n are comp 
work areas, with the a 
FIXED(15), to which th 
values are assigned; y 
to "variable" with the 
"temp" subscripts; "el 
"e3" are compiler-crea 



ajLf*««,aji are 

ppear as sub- 
variable; 

iler-created 

ttributes BINARY 

e expression 
is equivalent 
associated 
" "e2," and 

ted work areas 



Section 10: 



Statements 291 



having the attributes of " expres- 
sion! f " "expression2, " and "expres- 
sion3," respectively. In the simplest 
cases, there are no subscripts (i.e., 
n=0) and the first statement in the 
expansion is therefore el=expressionl. 

Additional rules for the above expan- 
sion follow: 

a. The above expansion only shows the 
result of one "specification." If 
the DO statement contains more 
than one "specification," the 
statement labeled NEXT is the 
first statement in the expansion 
for the next "specification," The 
second expansion is analogous to 
the first expansion in every 
respect. Thus, if a second "spe- 
cification" appeared in the DO 
statement, the second expansion 
would look like this: 

NEXT: temp JL =a i ; 



temp n =a n ; 

e5= express ion 5; 



v=e5; 
LABEL3: IF ... THEN GO TO NEXT1 ; 
IF Cexpression8) THEN; 

ELSE GO TO N£XT1; 
statement- 1 



statement execution, the associated 
elerrent expression is evaluated, and, 
if necessary, converted to a bit str- 
ing. If any tit in the resulting str- 
ing is 1, the statements of the DO- 
group are executed. If all bits are 
0, then, for Type 2, execution of the 
DO-group is terminated, while for Type 
3, only the execution associated with 
the "specification" containing the 
WHILE clause is terminated; repetitive 
execution for the next "specifica- 
tion," if one exists, then begins. 

5. In a "specification," "expression!" 
represents the initial value cf the 
control variable (i.e., "variable" or 
"pseudo-variable") ; "expressicnJ" 
represents the increment to be added 
to the control variable after each 
execution of the statements in the 
group; expression2 represents the ter- 
minating value of the control vari- 
able. Execution of the statements in 
a DO-group terminates for a "specifi- 
cation" as soon as the value cf the 
control variable is outside the range 
defined by "expression!" and "expre- 
ssion2." When execution for the last 
"specification" is terminated, con- 
trol, in general, passes to the state- 
ment following the DO-group. 

6. Control may transfer into a DO-group 
from outside the DO-group only if the 
DO-group is delimited by the DO state- 
ment in Type 1; that is, only if repe- 
titive execution is not specified. 
Consequently, repetitive DO-grcups 
cannot contain ENTRY statements. 



statement-m 
LABEL4: v=v+e7 ; 

GO TO LABEL 3; 
NEXT1: statement 

Note that statements 1 through m are 
not actually duplicated in the 
program. 

b. If the WHILE clause is omitted, 
the IF statement immediately pre- 
ceding statement-1 in the expan- 
sion is omitted. 

c. If "TO expression2" is omitted, 
the statement " e2=expression2" and 
the IF statement identified by 
LABEL2 are omitted. 

d. If both "TO expression2" and "BY 
expression3" are omitted, all 
statements involving e2 and ei, as 
well as the statement GO TO 
LABEL2, are omitted. 

The WHILE clause in Types 2 and 3 spe- 
cifies that before each repetition of 



7. The effect of allocating or freeing 
the control variable within the DO- 
group is undefined. 

The END Statement 

Function: 

The END statement terminates blocks and 
groups. 

General format: 

END (label] ; 

Syntax rules: 

If "label" is specified, it cannot be an 

element of a label array; that is, it can- 
not be subscripted. 

General rules: 

1. If a label follows END, the statement 
terminates the unterminated group or 
block headed by the nearest preceding 
DO, BEGIN, or PROCEDURE statement hav- 



292 



Paqe of GC28~20t*5-l, Issued September 30, 1971 by TNL GN28-318S 



ing that label. It also terminates 
any unterminated groups or blocks 
physically within that group or block. 

If a label does net follow END, the 
statement terminates that group or 
block headed by the near^ut preceding 
DO, BEGIN, or PROCEDURE statement for 
which there is no corref^ponding END 
statement. 

If control reaches an END statement 
for a procedure, it is treated as a 
RETURN statement* 



The ENTRY Statement 

Function: 

The ENTRY statement specifies a secon- 
dary entry point of a procedure. 

General format: 

entry name: (entry name:]... 

ENTRY i (parameter I, parameter] . . . ) ] 
[RETURNS (attribute. . . )'l ; 

Syntax rules: 

1. The only attributes that may be speci- 
fied in the RETURNS option of an ENTRY 
statement are the arithmetic, string, 
POINTER, OFFSET, AREA, and PICTURE 
attributes. The attributes specified 
determine the characteristics of the 
value returned by the procedure when 
it is invoked as a function at this 
entry point. 

2. A condition prefix cannot be specified 
for an ENTRY statement. 

General rules: 

1. The relationship established between 
the parameters of a secondary entry 
point and the arguments passed to that 
entry point is exactly the same as 
that established for primary entry 
point parameters and arguments. See 
Part I, Section 10, "Subroutines and 
Functions," for a complete discussion 
of this subject. 

2. As stated in syntax rule 1, the attri- 
butes specified in the RETURNS option 
of an ENTRY statement determine the 
characteristics of the value returned 
by the procedure when it is invoked as 
a function at this entry point. The 
value being returned by the procedure 
(i.e., the value cf the expression in 
a RETURN statement) is converted, if 
necessary, to correspond to the speci- 
fied attributes. If the RETURNS 
option is omitted, default attributes 
are applied, according to the first 



letter of the entry name used to 

invoke the entry point. 



The RETURNS keyword is mandatory for 
function procedures when function 
value attributes are explicitly 
specified. 

If an ENTRY statement has more than 
one label, each label is interpreted 
as though it were a single entry name 
for a separate ENTRY statement having 
the same parameter list and explicit 
attribute specification. For example, 
consider the statement: 

A: I: ENTRY; 

This statement is effectively the same 

as : 

A: ENTRY; 

I: ENTRY; 

Since the attributes of the returned 
value are not explicitly stated, the 
characteristics of the value returned 
by the procedure will depend on wheth- 
er the entry point has been invoked as 
A or I. 

The ENTRY statement must be internal 
to the procedure for which it defines 
a secondary entry point. It may not 
be internal to any block contained in 
this procedure; nor may it be within a 
DO-group that specifies repetitive 
execution. 



The EXIT Statement 

Function: 

The EXIT statement causes immediate ter- 
mination of the program that contains the 
statement; control returns to the command 
system, and the user is prompted with an 
underscore. The EXIT statement is equiva- 
lent to a STOP statement. 

General format: 

EXIT; 

General rule: 

EXIT causes the FINISH condition to be 
raised. If there is a FINISH on-unit, that 
cn-unit is executed first, and the program 
is terminated on normal return from the 
cn-unit. The completion values of the 
event variables associated with this pro- 
gram are set to • 1'B, and their status 
values to 1 (unless they are already 
nonzero) . 
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The , ^09h^[^r^trj.^ern : 

Function: 

The FORMAT statement specifies a format 
list that can be used by edit- directed 
transmission statements to control the for- 
mat of the data being transmitted. 

General formats 

label: (label: 1... FORMAT (format-list); 

Syntax rules; 

1. The "format list" roost be specified 
according to the rules governing for- 
mat list specifications with edit- 
directed transmission as described in 
Part I, Section 8, "Input and Output.* 

2* At least one "label" must be specified 

for a FORMAT statement. One of the 
labels Cor a label variable having the 

value of one of the labels) is the 
statement label designator appearing 
in a remote format item* None of the 

labels can be specified in a GO TO 
statement* 



General formats: 
Option 1 

FREE controlled-variable 

(, controlled-variable] , 



Option 2 

FREE [pointer-qualifier ->] 

based- variable I IN (area- variable) ] 
i, tpointer-gualif ier ->] 

based- variable 
ClNCarea-variable) i 1 . . * ; 

Syntax ruless 

1. In Option 1, the "controlled variable" 8 

is an element 9 array, or major struc- 
ture of the controlled storage class. 

2. In Option 2, the ^based variable* must 

be an unsukscript ed, level-one based 
• • variable* 

3. The forms of Option 1 and Option 2 can 
be combined in the same FREE 

statement. 



General rules: 

1. A GET or PUT statement may include a 
remote format item, R, in the format 
list of an edit-directed data specifi- 
cation. That portion of the format 
list represented by R roust be supplied 
by a FORMAT statement identified by 
the statement label specified with R. 

2. The remote format item and the FORMAT 
statement must he internal to the same 

block. 

3. If a condition prefix is associated 
with a FORMAT statement, it must be 
identical to the condition prefix 
associated with the GET or PUT state- 
ment referring to that FORMAT 
statement* 

aj. When a FORMAT statement is encountered 
in normal sequential flow, control 
passes around it, and the CHECK condi- 
tion will not be raised for a state- 
ment label attached to it. 

The FREE Statement 

Function: 

The FREE statement causes the stoiage 
allocated for specified based or controlled 
variables to be freed* For controlled 
variables, the next most recent allocation 
in the task is made available, and subse- 
quent references in the task to the identi- 
fier refer to that allocation. 



General rules: 



If a specified nonbased identifier has 
no allocated storage at the time the 
FREE statement is executed, it is an 
error . 

If the based variable is not qualified 
by pointer qualification, the pointer 
declared with the based variable will 
be used to identify the generation of 
data occupying the portion of storage 
to be freed. 



The amount of 
upon the attr 
able, includi 
at the time t 
applicable, 
for deter mini 
dues with th 
the variable 
the results a 



storaqe freed depends 
ibutes of the based va ri- 
ng bounds and/or lengths 
he storage is freed, if 
The user is responsible 
ng that this amount coin- 
e amount allocated. If 
has not been allocated, 
re unpredictable* 



A based variable can be osed to free 
storage only if that storage has been 
allocated for a based variable having 
identical data attributes , including 
values of bounds, lengths, and area 
size expressions. 

The IN option must be specified if the 
storage to be freed has been allocated 
using the IN option, and it must have 
been allocated in the area specified 
in the FREE statement. The IN option 
cannot appear in the FREE statement in 
any other circumstances. Note that 
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area assignment causes allocation of 
based storage in the target area; such 
allocations can be freed by the IN 
option naming the target area. 

Examples: 

1. FREE X,¥ f 2; 

2. The following excerpt froir a procedure 
illustrates the FREE statement in con- 
junction with an ALLOCATE statement: 

DECLARE AC100) INITIAL ( (100)0) 
CONTROLLED , C(100) # X(100); 



ALLOCATE A; 



C=A; 



FREE A; 



X=SIN(C**2 ♦ X/Y) ; 

3. In the example below, it is assumed 
the declarations specified in Example 
a of the ALLOCATE statement apply, 

FREE VALUE; 

Frees that portion of storage which is 
occupied by the allocation of VALUE 
identified by pointer P. 

FREE V->GROUP; 

Frees that portion of storage which is 
occupied by the allocation of GROUP 
identified by pointer V. The value 
V->DIW is used to determine the bound 
of VALUES, 



The GET Statement 

Function: 

The GET statement is a STREAK transmis- 
sion statement that can fce used in either 
of the following ways: 

1. It can cause the assignment of data 
from an external source (that is, from 
a data set) to one or more internal 
receiving fields (that is, to one or 
more variables) . 

2. It can cause the assignment of data 
from an internal source Cthat is, from 
a character-string variable) to one or 



more internal receiving fields (that 
is, to one or more variables) - 

General format: 

GET option-list; 

Following is the format of "option 
list": 

C [FILE (filename) 1 [data-specif icationl 
ICOPYl tSKIP[ (expression) ] 1} 

{STRING (character-string-name) 
data-specif icationl 

General rules: 



1. 



6. 



If neither the FILE(f ilename) option 
nor the STRING (character-string-name) 
option appears, the file option FILE 
(SYSIN) is assumed. 

One data specification must appear 
unless the SKIP option is specified. 

The options may appear in any order. 

The filename refers to a file which 
has been associated, by opening, with 
the data set which is to provide the 
values. It must be a STREAM INPUT 
file. 



The "character-string 
the character string 
vide the data to be a 
data list. This name 
reference to a built- 
Each GET operation us 
always begins at the 
specified string. If 
characters in this st 
the total number of c 
fied by the data spec 
ERROR condition is ra 



name" refers to 
that is to pro- 
ssigned to the 

may be a 
in function, 
ing this option 
beginning of the 

the number of 
ring is less than 
haracters speci- 
ification, the 
ised. 



When the STRING option is used under 
data-directed transmission, the ERROR 
condition is raised if an identifier 
within the string does not have a 
match within the data specification. 

The data specification is as described 
in Part I, Section 9, "Stream-Oriented 

Transmission." 

If the FILE (filename) option refers 
to a file that is not open in the cur- 
rent task, the file is implicitly 
opened in the task for stream output 
transmission. 

The COPY option, which may only be 
used with the FILE (filename) option, 
specifies that the source data, as 
read, is to be written, without 
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alteration, on the standard installa- 
tion print file. 



10. The SKIP option caus 
line to be defined f 
The expression, if p 
verted to an integer 
greater than zero, 
piler substitutes a 
data set is position 
the wth line relativ 
line. If the expres 
SKIP(l) is assumed* 
is always executed b 
transmitted. 



Examples: 
1. GET LIST (A,B,C) ; 



es a new current 
or the data set. 
resent, is con- 

w, which must be 
If not, the com- 
value of 1* The 
ed at the start of 
e to the current 
sion is omitted. 

The SKIP option 
efore any data is 



Specifies the list-directed transmis- 
f .on of the values to be assigned to 
a , B and C front the file SYSIN. 



If a GO TO statement transfers control 

f rcir within a block to a .point not 

contained within that block, the block 
is terminated. Also, if the transfer 
point is contained in a block that did 
net directly activate the block being 
terminated, all intervening blocks in 
the activation sequence are also ter- 
minated (see Part I, Section 6 t 
"Blocks, Flow of Control, and Storage 
Allocation, 1 * for examples and 
details). When one or more blocks are 
terminated by a GO TO statement, con- 
ditions are reinstated and automatic 
variables are freed just as if the 
blocks had terminated in the usual 
fashion* 

When a GO TO statement transfers con- 
trol out of a procedure that has been 
invoked as a function, the evaluation 
of the expression that contained the 
corresponding function reference is 
discontinued. 



2. GET FILE (BETA) EDIT (X,Y,Z) CA(5>," 
FC5,2>, AU0)>; 

Specifies the edit-directed transmis- 
sion of the values assigned to X, Y 
and Z from file BETA. 



The GO TO Statement 

Function: 

The GO TO statement causes control to be 
transferred to the statement identified by 
the specified label. 

General format; 



GO TO label-constant; 
| GO to element- label-variablej 
General rules: 



1. If an "element label variable" is spe- 
cified, the value of the latel vari- 
able determines the statement to which 

control is transferred. Since the 
label variable may have different 
values at each execution of the GO TO 
statement, control may not always pass 

to the same statement. 

2. A GO TO statement cannot pass control 

to an inactive block, 

3. A GO TO statement cannot transfer con- 
trol from outside a DO- group to a 
statement inside the DO-group it the 
DO-group specifies repetitive execu- 
tion, unless the GO TO terminates a 
procedure or on-unit invoked from 
within the DO-group* 



The IF Statement 



Function; 



The IF statement tests the value of a 
specified expression and controls the flow 
cf execution according to the result of 
that test. 

General format: 

IF element-expression 
THEN unit-1 
[ELSE unit-21 

Syntax rules: 

1. Each unit is either a single statement 

(except DO, END, PROCEDURE, BEGIN, 
DECLARE, FORMAT, or ENTRY), a DO- 
grcup, or a begin block. 

2. The IF statement itself is not ter- 
minated by a semicolon; however, each 
"unit* specified must b** terminated by 
a semicolon, 

3. Each "unit" may be labeled and may 
have condition prefixes. 

General rules: 

1. The element expression is evaluated 
and, if necessary , converted to a bit 
string. When the ELSE clause (that 
is, ELSE and its following "unit") is 
specified, the following occurs: 

If any bit in the string is 1, 
"unit-1" is executed, and control 
then passes to the statement fol- 
.., . ^lowing the IF statement. If all 

bits In the string have the value 
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0, "unit-1" is skipped and "unit-2" 
is executed, after which control 
passes to the next statement. 

When the ELSE clause is not specified, 
the following occurs: 

If any bit in the string is 1, 
"unit~l" is executed, and control 
then passes to the statement fol- 
lowing the IF statement. If all 
bits are 0, "unit-1" is not 
executed and control passes to the 
next statement. 

Each "unit" may contain statements 
that specify a transfer of control 
(e.g., GO TO); hence, the normal 
sequence of the IF statement may be 
overriden. 

2. IF statements may be nested; that is, 
either "unit", or both, may itself be 
an IF statement. Since each ELSE 
clause is always associated with the 
innermost unmatched IF in tne same 
block or DO-group, an ELSE with a null 
statement may be required to specify a 
desired sequence of control. 

The LOCATE Statement 

Function: 

The LOCATE Statement, which applies to 
BUFFERED OUTPUT files, causes allocation of 
a based variable in a buffer; it may also 
cause transmission of a previously allo- 
cated based variable. 

General format: 

LOCATE variable 

FILE (filename) [SET (pointer-variable) ) 
(KEYFROM(expression) ] ; 

Syntax rules: 

1. The options may appear in any order. 

2. The "variable" must be an unsub- 
scripted level 1 based variable. 

General rules: 

1. The FILE (filename) option specifies 
the file involved. This option must 
appear. 

2. Execution of a LOCATE statement causes 
the specified based variable to be 
allocated in the buffer. Components 
of the based variable that have been 
specified in REFER options are initia- 
lized. A pointer value is assigned to 
the pointer variable named in the SET 
option or, if the SET option is 
omitted, to the pointer variable spe- 
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If the KEYFROM (expression) option 
appears, the value of the expression 
is converted to a character string and 
is used as the key of the record when 
it is subsequently written. 

If the FILE(f ilename) option refers to 
an unopened file, the file is opened 
automatically; the effect is as if the 
LOCATE statement were preceded by an 
OPEN statement referring to the file. 

Example: 

LOCATE ALPHA SET (REC_POINT) FILE 
(BETA) ; 

The based variable ALPHA is allocated 
in a buffer and REC_ POINT is set to 
identify ALPHA in the buffer. Values 
may subsequently be assigned to ALPHA 
and the record will be written in the 
data set associated with file BETA 
when a subsequent LOCATE or WRITE 
statement is executed for file BETA or 
if BETA is closed, either explicitly 
or implicitly. 



The Null Statement 

Function: 

The null statement causes no action and 
does not modify sequential statement execu- 
tion. If the label of a null statement is 
enabled for the CHECK condition, CHECK is 
raised whenever control reaches the null 
statement. 

General format: 

[label:]. . .; 

The ON Statement 

Function: 

The ON statement specifies what action 
is to be taken (user-defined or standard 
system action) when an interruption results 
from the occurrence of the specified excep- 
tional condition. exceptional condition. 

General format: 
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ON condition [SNAP] (SYSTEM; | on- unit} 



Syntax rules: 



The condition may be any of those 
described in Part II, Section 8, "0N- 
Conditions" . 

The "on-unit" represents a user- 
defined action to be taken when an 
interruption results from the occur- 
rence of the specified "condition". 
It can be either a single unlabeled 
simple statement or an unlabeled begin 
block. If it is an unlabeled simple 
statement, it can be any simple state- 
ment except BEGIN, DO, END, RETURN, 
FORMAT, PROCEDURE, or DECLARE. If the 
on-unit is an unlabeled begin block, 
any statement can be used freely 
within that block, with one exception: 
A RETURN statement can appear only 
within a procedure nested within the 
begin block. 

Since the "on-unit" itself requires a 
semicolon, no semicolon is shown for 
the "on-unit" in the general format. 
However, the word SYSTEM must be fol- 
lowed by a semicolon. 



General rules: 

1. The ON statement determines how an 

interruption occurring for the speci- 
fied condition is to be handled. 
Whether the interruption is handled in 
a standard system fashion or by a 
user-supplied method is determined by 
the action specification in the ON 
statement, as follows: 

a. If the action specification is 
SYSTEM, the standard system action 
is taken. The standard system 
action is not the same for every 
condition, although for most con- 
ditions the system simply prints a 
message and raises the ERROR con- 
dition. The standard system 
action for each condition is given 
in Part II, Section 8, "ON- 
Conditions." (Note that the stan- 
dard system action is always taken 
if an interruption occurs and no 
ON statement for the condition is 
in effect . ) 

b. If the action specification is an 
"on-unit," the user has supplied 
his own interruption-handling 
action, namely, the action defined 
by the statement (s) in the on-unit 
itself. Tne on-unit is not 
executed when the ON statement is 
executed; it is executed only when 
an interruption results from the 



occurrence of the specified condi- 
tion (or if the interruption 
results from the condition being 
signaled by a SIGNAL statement) . 



2. The action specification (i.e., "on- 
unit" or SYSTEM) established ty 
executing an ON statement in a given 
block remains in effect throughout 
that block and throughout all clocks 
in any activation sequence initiated 
by that block, unless it is overridden 
by the execution of another ON state- 
ment or a REVERT statement, as 
follows : 

a. If a later ON statement specifies 
the same condition as a prior ON 
statement and this later ON state- 
ment is executed in a block that 
lies within the activation 
sequence initiated by the block 
containing the prior ON statement, 
the action specification of the 
prior ON statement is temporarily 
suspended, or stacked. It can be 
restored either by the execution 
of a REVERT statement, or by the 
termination of the block contain- 
ing the later ON statement. 

b. If the later ON statement and the 
prior ON statement are internal to 
the same invocation of the saire 
block, the effect of the prior ON 
statement is completely nullified. 

3. An on-unit^is always treated by the 
compiler as a procedure internal to 
tne block in which it appears. (Con- 
ceptually, it is enclosed in PROCEDURE 
and END statements.) Any names used 
in an on-unit do not belong to the 
invocation of the procedure or block 
in which the interruption occurred 
(and, hence, effectively, the proce- 
dure or block in which the on-unit is 
executed) but, rather, to the environ- 
ment of the invocation of the proce- 
dure or block in which the ON state- 
ment for that on-unit was executed. 
(Remember that an ON statement is 
executed as it is encountered in 
statement flow; whereas, the action 
specification for that ON statement is 
executed only when the associated 
interruption occurs.) 

4. A condition raised during execution 
results in an interruption if and only 
if the condition is enabled at the 
point where it is raised. 

a. The conditions AREA, OVERFLOW, 

FIXEDOVERFLOW, UNDERFLOW, ZERODI- 
VI DE, CONVERSION, all of the 
input/output conditions, and the 
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conditions CONDITION, FINISH, and 
ERROR are enabled by default, 

b. The conditions SIZE, STRINGRANGE, 
SUBSCRIPTRANGE, and CHECK are dis^ 
abied by default. 

c. The enabling and disabling of 
OVERFLOW, FIXEDOVERFLOW, UNDER- 
FLOW, ZERODIVIDE, CONVERSION, 
SIZE, STRINGRANGE, SUBSCRIPT RANGE, 
and CHECK can be controlled by 
condition prefixes. 

5. If on-unit is a single statement, it 
cannot refer to a remote format 
specification. 

6. If SNAP is specified, then when the 
given condition occurs and the inter- 
ruption results, a calling trace is 
listed; that is, a trace of all of the 
procedures active at the time the 
interruption resulted is printed on 
SYSOUT. 



The OPEN Statement 

Function: 

The OPEN statement opens a file by asso- 
ciating a file name with a data set. It 
also can complete the specification of 
attributes for the file, if a complete set 
of attributes has not been declared for the 
file being opened. 

General format: 

OPEN FILE (file- name) [options-group] 
[ ,FILE(file-name) (options-group) ) . . ♦ ; 

where "options-group* is as follows; 

I DIRECT | SEQUENTIAL] 

[BUFFERED) UNBUFFERED] 

I STREAM | RECORD] 

( INPUT I OUTPUT | UPDATE ] 

[KEYED] [EXCLUSIVE] 

[BACKWARDS] 

[TITLE (element-expression) ] 

[PRINT] 

(LINESIZE (element-expression) ) 

[PAGESIZE(element-expression) } 

Syntax rules: 

1. The INPUT, OUTPUT, UPDATE, STREAM, 

RECORD, DIRECT, SEQUENTIAL, BUFFERED, 
UNBUFFERED, KEYED, EXCLUSIVE, BACK- 
WARDS, and PRINT options specify 
attributes that augment the attributes 
specified in the file declaration; for 
rules governing which of these attri- 
butes can be applied together, see 
Part I, Section 8, "Input and Output," 
and the corresponding attributes in 
Part II, Section 9, "Attributes." 



2- The options in an "option group" and 
the FILE option for a file may appear 
in any order. 

3. The "file name" is the name of the 
file that is to be associated with a 
data set. Several files can be opened 
by one OPEN statement. 

General rules: 

1. The opening of an already open file 
does not affect the file if the second 
opening takes place in the saire task. 
In such cases, any expressions in the 
"options-group" are evaluated, but 
they are not used. 

2. If the TITLE option is specified, the 
"element expression" is converted to a 
character string, if necessary, the 
first eight characters of which iden- 
tify the DDEF command (the DDNAME) to 
be associated with the file. If this 
option does not appear, the first 
eight characters of the file name 
(padded or truncated) are taken to be 
the CDNAME. Note that this is not the 
same truncation as that for external 
names. If the file name is a parame- 
ter, the identifier of the original 
argument passed to the parameter, 
rather than the identifier of the pa- 
rameter itself, is used as the 
identification. 

3. The LINESIZE option can be specified 
only for a STREAM OUTPUT file. The 
expression is evaluated, converted to 
an integer, and used as the length of 

a line during subsequent operations on 
the file. New lines may be started by 
use of the printing and control format 
items or by options in a GET or PUT 
statement. If an attempt is made to 
position a file past the end of a line 
before explicit action to start a new 
line is taken, a new line is automat- 
ically started, and the file is posi- 
tioned to the start of this new line. 
If no line size is given for a PRINT 
file, an implementation-defined 
default of 120 characters is supplied." 

The LINESIZE option cannot be spe- 
cified for an INPUT file. The line 
size taken into consideration whenever 
a SKIP option appears in a GET state- 
ment is the line size that was used to 
create the data set, if any; other- 
wise, the line size is taken to be the 
current length of the logical record 
(minus control bytes, for format- V 
records). The maximum line size is 
32,751 for format-V records, and 32, 
759 for format-U and -F records. 

U. The PAGESIZE option can be specified 
only for a file having the STREAM and 
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PRINT attributes. The element expres- 
sion is evaluated and converted to an 
integer , which represents the maximum 
number of lines to a page. During 
subsequent transmission to the PRINT 
file, a new page ir.ay be started by use 
of the PAGE format item or by the PAGE 
option in the POT statement. If a 
page becomes filled and more data 
remains to be printed before action to 
start a new page is taken , the ENDPAGE 
condition is raised. For the TSS/360 
PL/1 compiler, the maximum siie of a 
page is 32 # 767 lines; the minimum is 1 
line. If PAGESIZE is not specified , 
the default is 60 lines per page* 



The PROCEDURE Statement 

Function: 

Til,- PPOCEDUPE statement has the follow- 
ing functions: 

• It heads a procedure* 

• It defines the primary entry point to 
the procedure. 

• It specifies the parameters, if any, 
for the primary entry point* 

• It may specify certain special charac- 
teristics that a procedure can have. 

■ It may specify the attributes of the 
value that is returned by the procedure 

if it is invoked as a function at its 
primary entry point. 

General format: 

entry-name: t entry-name: J .. . 

PROCEDURE! (parameter [.parameter! . • . ) ] 

[OPTIONS Coption-iist) 1 

[RECURSIVE] 

[RETURNS (attribute. * . ) ] 

[ORDER | REORDER] ; 

Syntax rules: 

1. OPTIONS and RECURSIVE are special pro- 
cedure specifications that the user 
can specify* They and the other PL/I- 
defined options can appear in any 
order and are separated by blanks, 

2. The "option list* 8 of OPTIONS specifies 
one or more additional implementation- 
defined options; it may contain the 
MAIN and REENTRANT options, separated 
by commas. MAIN specifies that the 
procedure is the initial procerSjre, to 
be invoked by the time-sharing system 
as the first step in the execution of 
the PL/I program; REENTRANT specifies 
that the compiler must generate reent- 
erable code; that is f code that does 



not wodify itself during its 

execution* 

Mote i It. is up to the programmer to 
ensure that any static variables are 
read-only, if the program is to be 
truly reentrant. 

3. • ORDfR and RBDEDER are options used to 
control the optimization performed by 
the compiler. The selected option 
applies to all nested blocks unless 
overridden* CThese options are also 
allowed on BEGIN statements.) If 
neither option is given for an extern- 
al procedure, ORDER is assumed. 

General rules: 



1. 



**. 



When the procedure is invoked, a rela- 
tionship is established between the 
arguments passed to the procedure and 
the parameters that represent those 
arguments in the invoked procedure. 
This topic is discussed in Part I # 
Section 12, ^Subroutines and 
Functions. " 

OPTIONS may be specified only for an 
external procedure* and at least one 
'external procedure must have the 
OPTIONS (MAIN) designation; if more 
than one is so designated B the system 
-will Invoke the one that appears 
first f physically. OPTIONS applies to 
all of the entry points (both primary 
and secondary) that the procedure for 
which it has been declared might have. 

RECURSIVE must be specified if the 
procedure might he invoked recursive- 
ly; thas. is if it might be re- 
activated while it is still active, 
if specified, it applies to all of the 
entry points {primary and secondary) 
that the ^tocedure wight have* It 
applies only to the procedure for 
which it is declared. 
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base, precision* and scale can differ 
according to the entry name.) 

5. If a PROCEDURE statement has more than 
one entry name, the iiriit name can be 
considered as the only label of the 
statement; each subsequent entry name 
can be considered as a separate ENTRY 
statement having the same parameter 
list and RETURNS option as the PROCE- 
DURE statement. Thus, the statement: 

A: I: PROCEDURE RETURNS (BINARY 
FIXED) ; 

is effectively the same as: 

A; PROCEDURE RETURNS ( BINARY FIXED); 

I: ENTRY RETURNS (BINARY FIXED); 
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The REORDER option specifies that 
execution of the block must produce a 
result that is in accordance with the 
strict definition of PL/I unless a 
computational or system-action inter- 
ruption occurs during execution of the 
block; the result is then allowed to 
deviate as follows: 



a. After a computational or system- 
action interruption has occurred 
during execution of the blcck, the 
values of variables modified, 
allocated, or freed in the block 
are guaranteed only after normal 
return from an on-unit or when 
accessed by the ONCHAR and 
ONSOURCE condition built-in 
functions . 

b. The values of variables modified, 
allocated, or freed in an on-unit 
for a computational or system- 
action condition (or in a block 
activated by such an on-unit) are 
not guaranteed on return from the 
on-unit into the block, except for 
values modified by the ONCHAR and 
ONSOURCE pseudo variables. 

A program is in error if a computa- 
tional or system-action interruption 
occurs during execution of the block 
and this interruption is followed by a 
reference to a variable whose value is 
not guaranteed in such circumstances . 



The PUT Statement 



The ORDER option specifies thcit the 
normal language rules are not to be 
relaxed; i.e., any optimization must 
be such that the execution of a block 
always produces a result that is in 
accordance with the strict definition 
of PL/I. This n.eans that the values 
of variables set. by execution of all 
statements prior to computational or 
system-action interruptions are 
guaranteed in an on-unit entered as a 
result of the interruption, or any- 
where in the program afterwards. Note 
that the strict definition now allows 
the compiler to optimize common expre- 
ssions (see note below), where safely 
possible, by evaluating them once only 
and saving the result, rather than 
reevaluating for each reference. 

Note : A common expression is an ex- 
pression that occurs more than once in 
a program but is obviously intended to 
result in the same value each time 
that it is evaluated, i.e., if a later 
expression is identical to an earlier 
expression, with no intervening modi- 
fication to an operand, the expre- 
ssions are said to be common • 



Function : 

The PUT statement is a STREAM transmis- 
sion statement that can be used in either 
cf the following ways: 

1. It can cause the values in one or more 
internal storage locations to be tran- 
smitted to a data set on an external 
medium. 

2. It can cause the values in one or more, 
internal storage locations to be 
assigned to an internal receiving 
field (represented by a character- 
string variable). 

General format: 

PUT option list; 

Following is the format of •option list": 



f (FILE(f ilename) 1 (data-specif icationl 
PAGE (LINE (element-expression) J] ~ 
SKIP ( (element- express ion) I 
LINE (element-expression) 
(STRING (character-string- variable) 
data-specification! 



1 1 

[{ 
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Syntax rules: 



If neither the FILE nor STRING option 
appears, the specification FILE CSYS-* 
OUT) is assumed. If such a PUT state- 
ment lies within the scope of a 
declaration of the identifier SYSOUT, 
SYSOUT roust have teen declared as FILE 
STREAM OUTPUT. If the POT statement 
does not lie within the scope of a 
declaration of SYSOUT, SYSOUT is the 
standard system output file. 

The FILE option specifies transmission 

to a data set on an external medium. 
The file name in this option is the 

name of the file that has been asso- 
ciated (by implicit or explicit open- 
ing) with the data set that is to 
receive the values. This file roust 
have the OUTPUT and STREAM attributes. 

' he STRING option specifies transmis- 
sion from internal storage locations 
(represented by variables or expre- 
ssions in the ""data specification") to 
a character string (represented by the 
"cb-iracter-string variable 88 ). The 
"character-string variable" can be a 
string pseudo-variable. 

The "data specification" option is as 

described in Part I, Section 9, 
"St ream- Oriented Transmission. " 

The PAGE, SKIP, and LINE options can- 
not appear with the .STRING option. 

The options may appear in any order; 

at least one m u s t a p pea r . 



General rules: 
1 



If the FILE option is specified, and 
the "file name" refers to an unopened 
file, the file is opened implicitly as 
an OUTPUT file. 



2. If the STRING option is specified, the 
PUT operation begins assigning values 
to the beginning of the string Cthat 

is, at the left-most character posi- 
tion) , after appropriate conversions 
have been performed. Blanks and deli- 
miters are inserted as usual. If the 
string is not long enough to accomod- 
ate the data, the ERROR condition is 
raised. 



7. 



in the same PUT statement, in which 
case, the PAGE option is applied 
first. 



The PAGE option causes a new current 
page to be define^ within the data 
set. If a data specification is pre- 
sent, the transmission of values 
occurs after the definition of the new 
page. The page remains current until 
the execution of a PUT statement with 
the PAGE option # until a PAGE format 
item is encountered, or until an END- 
PAGE interruption results in the 
definition of a new page. A new cur- 
rent page implies line one. 

The SKIP option causes a new current 
line to be defined for the data set. 
The expression, if present, is con- 
verted to an integer w, which for non- 
PRINT files must be greater than zero. 
The data set is positioned at the 
start of the wth line relative to the 
current line. If the expression is 
omitted, SKIPC1) is assumed. 

For PRINT files w may be less than or 
equal to zero? in this case, the 
effect is that of a carriage return 
with the same current line. If less 
than w lines remain on the current 
page when a SK.IP(w) is issued, ENDPAGE 
is raised. 

The LINE option causes a new current 
line to be defined for the data set. 
The expression is converted tc an 
integer w. The LINE option specifies 
that blank lines are to be inserted so 
that the next .line will be the wth 
line of the current page* If at least 
w lines have already been written on 
the current page or if w exceeds the 
limits set by the PAGESIZE option of 
the OPEN statement, the ENDPAGE condi- 
tion is raised. If w is less than or 
equal to zero, it is assumed to be 1. 

If tSe FILE (filename) option refers to 
a file that is not open, the file is 
opened implicitly for stream output. 



Examples : 

1. PUT DATA (A, B,C) ; 

Specifies the data- directed transmis- 
sion of the values A, B and C to the 

file SYSOUT. 



3. The PAGE and LINE options can be spe- 
cified for PRINT files only. All of 
the options take effect before trans- 
mission of any values defined by the 

data specification, if given. Of the 
three, only PAGE and LINE may appear 



PUT FILE (LIST) EDIT (X,Y,Z) 
PAGE; 



CAC10) ) 



Specifies that a new page is to be 
defined for the print file LIST. The 
values of X, Y and Z are placed start- 
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ing in the first printing position of 
the new page. Each of the values will 
use the A(10) format item. 

The READ Statement 

Function: 

The READ statement causes a record to be 
transmitted from a RECORD INPUT or RECORD 
UPDATE file to a variable or buffer. 

General format: 



READ option-list; 

I The format of "option list" is shown in 
Figure 51. 

General rules : 

1. The options may appear in any order. 

2. The FILECf ilename) option specifies 
the file from which the record is to 
be read. This option must appear. If 
the file specified is not open, it is 
opened. 

3. The INTO (variable) option specifies an 
unsubscripted level 1 variable into 
which the record is to be read. It 
cannot be a parameter, nor can it have | 
the DEFINED attribute. 

4. If the variable in the FROM or INTO 
option is a structure, it cannot con- 
tain VARYING strings. However it is 
possible to have a VARYING string ele- 
ment variable in these options. This 
is an implementation restriction. 

5. The KEY and KEYTO options can be spe- 
cified for KEYED files only. 

6. The KEY option must appear if the file 
has the DIRECT attribute. The "ex- 
pression" is converted to a character 
string that represents a key. It is 
this key that determines which record 
will be read. 

The KEY option may also appear for 
files having the SEQUENTIAL and KEYED 
attributes. In such cases, the file 



is positioned to the record having the 
specified key. Thereafter, records 
may be read sequentially from that 
point on by using READ statements 
without the KEY option. For System/ 
360 implementations, the data set must 
have the INDEXED organization. 

The KEYTO option can be given only if 
the file has the SEQUENTIAL and KEYED 
attributes. It specifies that the key 
of the record being read is to be 
assigned to the "character-string 
variable" according to the rules for 
character-string assignment. If prop- 
er assignment cannot be made, the KEY 
condition is raised. 

For INDEXED, the recorded key is 
padded or truncated on the right to 
the declared length of the character- 
string variable. The KEY condition is 
not raised for such padding or 
truncation. 

Note : The KEYTO option cannot specify 
a variable declared with a numeric 
picture specification. 

The EVENT option allows processing to 
continue while a record is being read 
or ignored. This option cannct be 
specified for a BUFFERED file. 

When control reaches a READ statement 
containing this option, the "event 
variable" is made active (that is, it 
cannot be associated with another 
event) and is given the completion 
value ' O'B, provided that the UNDE- 
FINEDFILE condition is not raised by 
an implicit file opening (see "Note" 
below) . The event variable reirains 
active and retains its • Q'B completion 
value until control reaches a WAIT 
statement specifying that event vari- 
able. At this time, either of the 
following can occur: 

a. If the READ statement has been 

executed successfully and ncne of 
the conditions ENDFILE, TRANSMIT, 
KEY or RECORD has been raised as a 
result of the READ, the event 
variable is set complete (given 



[INTO (variable) } 



(KEY ( expression ) 

_(keyTO( character-string-variable 
KEY (express 



1 



[EVENT (event- variable) 1 



["{KEY (expression) Y 

L\KEYTO (character-string- variable)). 



[FILE 

(file name)^lSET(pointer-variable) 1| 

"KEYTO (charac 

[IGNORE (expression) 1 (EVENT (event -variable) 1 

L . * . . . . . . , . -1-J 

Figure 51. Format of Option List for READ Statement 
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the completion value "l'B), and is 
made inactive, that is, it can be 
associated with another event. 

b. If the READ statement has resulted 
in the raising of ENDFILE, TRANS- 
MIT, KEY, or RECORD, the interrup- 
tion for each of these conditions I 
does not occur until the WAIT is 
encountered. At such time, the I 
corresponding on-units (if any) 
are entered in the order in which 
the conditions were raised. After 
a return from the final on- unit, 
or if one of the on-units is ter- 
minated by a GO TO statement, the 
event variable is given the com- 
pletion value 'l'B and is made 
inactive. 

Note : If the READ statement causes an 
implicit file opening that results in 
the raising of UNDEFINEDFILE, the on- 
unit associated with this condition is 
entered immediately and the event 
variable remains unchanged; that is, 
the event variable remains inactive 
and retains the same value it had when 
the READ was encountered. If the on- 
unit does not correct the condition, 
then, upon normal return from the on- 
unit, the ERROR condition is raised; 
if the condition is corrected in the 
on-unit, that is, if the file is 
opened successfully, then, upon normal I 
return from the on-unit, the event 
variable is set to ' O'B, it is made 
active, and execution of the READ 
statement continues. 



course, the record has been explicitly 
unlocked by one of the above methods). 



10. The SET option specifies that the 

record is to be read into a buffer and 
that a pointer value is to be assigned 
to the named pointer variable. The 
pointer value identifies the record in 
the buffer. 



11. The IGNORE option may be specified for 
SEQUENTIAL INPUT and SEQUENTIAL UPDATE 
files. The expression in the IGNORE 
option is evaluated and converted to 
an integer. If the value, n, is 
greater than zero, n records are 
ignored; a subsequent READ statement 
for the file will access the Cn+l)th 
record. A READ statement without an 
INTO, SET, or IGNORE option is equiva- 
lent to a READ with an IGNORE (1). 

12. An INDEXED data set that is accessed 
by a KEYED SEQUENTIAL INPUT file or a 
KEYED SEQUENTIAL UPDATE file may be 
positioned by issuing a READ statement 
with the KEY option. The specified 
key will be used to identify the reco- 
rd required. Thereafter, records may 
be read sequentially from that point 
by use of READ statements without the 
KEY option. 

For BUFFERED SEQUENTIAL files, two 
positioning statements can be used, 
with the following formats: 



9. Any READ statement causes the record 
to be locked. A locked record cannot 
be read, deleted, or rewritten by any 
other task until it is unlocked. Any 
attempt to read, delete, or rewrite a 
record locked by another task results 
in a wait. Subsequent unlocking 
occurs as a result of one of the fol- 
lowing actions: 

a. The locking task executes a 
REWRITE or DELETE statement that 
specifies the same file name and 
key as the locking READ statement; 

b. The locking task executes a CLOSE 
statement for the file specified 
in the locking READ statement; 

c. The locking task is completed. 

Note that a record is considered 
locked only for tasks other than the 
task that actually locks it; in other 
words, a locked record can always be 
read by the task that locked it and 
still remain locked as far as other 
tasks are concerned (unless, of 



READ FIIE (filename) INTO (vari- 
able) KEY (expression) ; 

READ FILE (filename) SET (pointer- 
variable) KEY (expression) ; 

For UNBUFFERED SEQUENTIAL files, 
only the first form shown immediately 
above can be used, and it may be spe- 
cified with the EVENT option. 

Examples : 

1. READ FILE (ALPHA) SET ( REC_ICENT) ; 

The next record from the data set 
associated with ALPHA is made avail- 
able and the pointer variable RESI- 
DENT is set to identify the record in 
the buffer. 



2. READ FILE (BETA) KEY (VALUE) 
(WORK) ; 



INTO 



The record identified by the key VALUE 
is transmitted from the data set asso- 
ciated with BETA into the variable 
WORK. 
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The RETURN Statement 



R - A(P,Q) ; 



Function: 

The RETURN statement terminates execu- 
tion of the procedure that contains the 
RETURN statement. If the procedure has not 
been invoked as a task, the RETURN state- 
ment returns control to the invoking proce- 
dure. The RETURN statement may also return 
a value. 

General format: 

Option 1. 

RETURN; 
Option 2. 

RETURN (expression) ; 
General rules: 

1. Only the RETURN statement in Option 1 
can be used to terminate procedures 
not invoked as function procedures; 
control is returned to the point log- 
ically following the invocation. 

If the RETURN statement terminates 
the major task, the FINISH condition 
is raised prior to the execution of 
any termination processes. 

2. The RETURN statement in Option 2 is 
used to terminate a procedure invoked 
as a function procedure only. Control 
is returned to the point of invoca- 
tion, and the value returned to the 
function reference is the value of the 
expression specified converted to con- 
form to the attributes declared for 
the invoked entry point. These attri- 
butes may be explicitly specified at 
the entry point; they are otherwise 
implied by the initial letter of the 
entry name through which the procedure 
is invoked. 



END; 

In the assignment statement (R=A(P,Q);), 
procedure B invokes procedure A as a func- 
tion. Procedure B specifies that the ele- 
nent expression in the RETURN statement is 
to be evaluated; since X and Y are 
floating-point variables and the RETURNS 
option of the PROCEDURE statement specifies 
that the value returned is to be fixed- 
point, the value of the expression is con- 
verted to fixed-point, and this value is 
returned to B. 



The REVERT Statement 

Function: 

The REVERT statement is used to cancel 
the effect of one or more previously 
executed ON statements. It can affect only 
ON statements that are internal to the 
block in which the REVERT statement occurs 
and which have been executed in the same 
invocation of that block. Execution of the 
REVERT statement in a given block cancels 
the action specification of any ON state- 
ment for the named condition that has been 
executed in that block; it then reestab- 
lishes the action specification that was in 
force at the time of activation of the 
block. 

General format: 

REVERT condition; 

Syntax rule: 

The "condition* is any of those 
described in Part II, Section 8, 
•ON-Condit ions . " 

General rule: 



3. If control reaches an END statement 
corresponding to the end of a proce- 
dure, this END statement is treated as 
a RETURN statement (of the Option 1 
form) for the procedure. 

Example: 

A: PROCEDURE (X,Y) RETURNS (FIXED); 
DECLARE (X,Y) FLOAT; 



The execution of a REVERT statement has 
the effect described above only if (1) an 
ON statement, specifying the same condition 
and internal to the same block, was 
executed after the block was activated and 
(2) the execution of no other similar 
REVERT statement has intervened. If either 
of these two conditions is not met, the 
REVERT statement is treated as a null 
statement. 



The REWRITE Statement 



B: 



RETURN (X»*2*Y**2> ; 

END; 

PROCEDURE; 

DECLARE A ENTRY RETURNS (FIXED); 



Function: 

The REWRITE statement can be used only 
for update files. It replaces an existing 
record in a data set. 



General format: 
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REWRITE FILE (file- name) 
f FROM (variable) 1 
fKEY (element-expression) 1 
f EVENT (event-variable) I 

Syntax rules: 

1. The options can appear in any order. 

2. The "FILE (file- name)" option speci- 
fies the name of the file, which must 
have the UPDATE attribute. 

3. The ^variable" in the FROF option must 
be an unsubscripted level 1 variable 

(that is, a variable not contained in 
an array or structure). It cannot 

have the DEFINED attribute and it can- 
not be a parameter. it represents the 
record that will replace the existing 
record in the specified file. 

General inles: 

1. If the file whose name appears in the 

FILE specification has not been 
opened, it is opened implicitly with 

the attributes RECORD and UPDATE. 

2. The KEY option must appear if the file 
has the DIRECT attribute; it cannot 
appear otherwise. The element- 
expression is converted to a character 
string* This character string is the 
source key that determines which reco- 
rd is to be rewritten. For SEQUENTIAL 
files associated with INDEXED data 
sets in System/36 implementations, 
the key must be the same as the one it 
replaces . 

3. For SEQUENTIAL UPDATE files, the reco- 
rd sizes must match. If the new 
length is shorter than the original 
record, the record is not written, and 

no error indication is given* If the 
new length is greater than the origi- 
nal, the record is not written, and 
error message IHE112I is issued. 

For DIRECT UPDATE files, the record 
sizes need not match- 

4. The FROM option must be specified for 

UPDATE files having either the DIRECT 
attribute or both the SEQUENTIAL and 
UNBUFFERED attributes. A REWRITE 

statement in which the FROM option has 
not been specified has the following 
effect: if the last record was read 

by a READ statement with the INTO 
option, REWRITE without FRO*> has no 
effect on the record in the data set; 
if the last record was read by a READ 

statement with the SET option, the 

record will be updated by whatever 
assignments were made in the buffer 

identified by the pointer variable in 
the SET option. 



1 5. 



6, 



If the variable in the FROM option is 
a structure, it cannot contain VARYING 
strings* However it is possible to 
have a VARYING string element variable 
in these options. This is an imple- 
mentation restriction. 

The EVENT option allows processing to 
continue while a record is being re- 
written* This option cannot be speci- 
fied for a SEQUENTIAL BUFFERED file. 

When control reaches a REWRITE state- 
ment containing this option, the event 
variable is made active (that is, it 
cannot be associated with another 
event) and is given the completion 
value 'O'B, provided that the UNDE- 
FINEDF1LE condition is not raised by 
an implicit file opening (see "Note* 
below)- The event variable remains 
active and retains its s * F3 completion 
value until control reaches a WAIT 
statement specifying that event vari- 
able. At this time, either of the 
following can occur: 

a. If the REWRITE statement has been 
executed successfully and none of 
the conditions TRANSMIT, KEY, or 
RECORD has been raised as a result 
of the REWRITE* the event variable 
is set complete (given the comple- 
tion value f l s B), and the event 
variable is made inactive (that 
is, it can be associated with 
another event) . 

b. If the REWRITE statement has 
resulted in the raising of TRANS- 
MIT, KEY, or RECOf-D, the interrup- 
tion for each of these conditions 
does not occur until the WAIT is 
encountered. At such time, the 
corresponding on-units (if any) 
are entered in the order in which 
the conditions were raised. After 
a return from the final on -unit, , 
or if one of the on-units is ter- 
minated by a GO TO statement, the 
event variable is given the com- 
pletion value S 1"B and is made 
inactive. 

Note : If the rewkH'E statement causes 
an implicit file opening thai, result*- 
in the raising of UNDEFINEDFILE, the. 
on-unit associated with this condition 
is entered immediately arid the event 
variable remains unchanged, that is # 
the event variable regains inactive 
and retains the same value it nad when 
the REWRITE was encountered. If the 
on-unit does not correct the condi- 
tion, then # upon normal return from. 
the on-unit, the ERROR condition is 
raised; if the condition is corrected 
in the on-unit, t hat is # if the file 
is opened successfully, then, upon 
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normal return from the on-unit, the 
event variable is set to • Q'B, it is 
made active, and execution of the 
REWRITE statement continues. 



The SIGNAL Statement 

Function: 

The SIGNAL statement simulates the 
occurence of an interruption. It may be 
used to test the current action specifica- 
tion for the associated condition. 

General format: 

SIGNAL condition; 

Syntax rule: 

The "condition" is any one of those 
described in Part II, Section 8, 
"ON-Conditions." 

General rules: 

1. When a SIGNAL statement is executed, 
it is as if the specified condition 
has actually occurred. Sequential 
execution is interrupted and control 
is transferred to the current on-unit 
for the specified condition. After 
the on-unit has been executed, control 
normally returns to the statement 
immediately following the SIGNAL 
statement. 

2. The on-condition CONDITION can cause 
an interruption only as a result of 
its specification in a SIGNAL 
statement. 

3. If the specified condition is dis- 
abled, no interruption occurs, and the 
SIGNAL statement becomes equivalent to 
a null statement. 

4. If there is no current on-unit for the 
specified condition, then the standard 
system action for the condition is 
performed. 



The STOP Statement 

Function: 

The STOP statement causes immediate ter- 
mination of the program? control is 
returned to the command system, and the 
user is prompted with an underscore. 

General format: 

STOP; 

General rule: 



Prior to any termination activity the 
FINISH condition is raised in the program 
in which the STOP is executed. If there is 
a FINISH on-unit, that on-unit is executed 
first, and the program is terminated on 
normal return from the on-unit. 

The UNLOCK Statement 

Function: 

The UNLOCK statement is ignored in TSS/ 
360, since all records are automatically 
locked when a file is opened for direct 
access. 

The WAIT statement 



Function: 

The execution of a WAIT statement within 
an activation of a block gives the WAIT 
statement control for that activation of 
that block until certain specified events 
have completed. 

General format: 

WAIT (event-name t , event-name] ... ) 
i (element-expression) 1 ? 

General rules: 

1. Control for a given block activation 
remains within this statement until, 
at possibly separate times during the 
execution of the statement, the 
condition 

COMPLETION (event-name) = • l f E 

has been satisfied, for some or all of 
the event names in the list. 

2. If the optional expression does not 
appear, all the event names in the 
list rr.ust satisfy the above condition 
before control returns to the next 
statement in this task following the 
WAIT. 

3. If the optional expression appears, 
the expression is evaluated when the 
WAIT statement is executed and con- 
verted to an integer. This integer 
specifies the number of events in the 
list that must satisfy the above con- 
dition before control for the block 
passes to the statement following the 
WAIT. Of course, if an on-unit 
entered due to the WAIT is terminated 
abnormally, control might not pass to 
the statement following the WAIT. 

If the value of the expression is 
zerc or negative, the WAIT statement 
is treated as a null statement. If 
the value of the expression is greater 
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than the number, n, of event names In 
the list, the value is taken to be n. 
If the statement refers to an array 
event name, then each of the array 
elements contributes to the count. 

4. It the event variable named in the 
list is associated with an I/O opera- 
tion initiated in the same task as the 

WAIT, the condition in Rule 1 will be 
satisfied when the 1/0 operation is 
completed* The execution of the WAIT 
is a necessary part of the completion 
of an 1/0 operation. If prior to, or 
during, the WAIT all transmission 
associated with the I/O operation is 
terminated, then the WAIT perforins the 
following action: If the transmission 
has finished without requiring any I/O 
conditions to be raised, the event 
variable is set complete Cthat is f 
COMPLETION (event name) = f l'B)« If 
'the transmission has been terminated 
out has required conditions to be 
raised, the event variable is set 
abnormal (that is, STATUS Cevent name) 

= 1) and all the required ON condi- 
tions are raised* On return from the 
last on-unit, the event variable is 
set complete. 

5. The order in which CN conditions for 
different I/O events are raised is not 
dependent on the order of appearance 

of the event names in the list. If an 
ON condition for one event is raised, 

then all otihei conditions for that 
event are raised before the WAIT is 
terminated or before any other I/O 
conditions are raised unless an 
abnormal return is made from one of 
the on- units thus entered* The rais- 
ing of ON conditions for one event 
implies nothing about the completion 
or termination of transmission of 
other events in the list. 

6. If an abnormal return is made from any 
on-unit entered from a WAIT, the asso- 
ciated event variable is set complete, 
the execution of the WAIT is ter- 
minated, and control passes to the 
point specified by the abnormal 
return. 

7. If a WAIT statement is executed and 
the events required to satisfy the 
WAIT contain a mixture of I/O and non- 
I/O events, ail non- I/O events wij 1 be 
set complete before any of the I/O 
events. 



then these incomplete events will not 
be set complete until the execution of 
another WAIT referring to these events 
in this s^r^"' {..r;^edure. 

The CALL statement will prevent execu- 
tion of the program* The EVENT option 
must not be associated with a call 
statement under TSS/360. 

Examples 

PI: PROCEDURE; 



CALL P2 EVENTCEP2); 



WA1TIEP2) ; 



END; 



The WRITE Statement 
Function: 

The WRITE statement is a RECORD trans- 
irission statement that transfers a record 
from a variable in internal storage to an 
OUTPUT or UPDATE file- 
General format: 

WRITE FILE (file-name) FROM (variable) 
C KEYFROM ( element- expression ) J 
[EVENT (event-variable) J ; 

Syntax rules: 

* 1. The FILE and FROM specifications and 
the KEYFRCM and EVENT options may 
appear in any order. 

2. The "file name" specifies the file in 

which the record is to be written* 
This tile must be a RECORD file that 
h<*r either the OUTPUT attribute oi the' 
DIRECT and UPDATE attributes. 

3. The "variable" in the FROM specifica- 
tion must be an unsubscr ipted level 1 
variable Cthat is, a variable not con- 
tained in an array or structure). It 
cannot have the DEFINED attribute and 
it cannot be a parameter. It contains 
the record to be written. 



8. If some of the event names in the WAIT 
list are associated with I/C opera- 
tions and have not been set complete 
before the WAIT is terminated (either 
because enough events have teen com- 
pleted or due to an abnormal return) , 



General rules; 



If the file is not open, it. is opened 
implicitly with the attributes RECORD 
and OUTPUT (unless UPDATE has been 
declared) . 



308 



If the KEYFROM option is specified, 
the "element expression" is converted 
to a character string. This character 
string is the source key that speci- 
fies the relative location in the 
dataset where the record is written. 
For INDEXED data sets, KEYFROM also 
specifies a recorded key whose length 
is determined by the KEYLEN suboperand 

The EVENT option allows processing to 
continue while a record is being writ- 
ten. This option cannot te specified 
for a SEQUENTIAL BUFFERED file. 

When control reaches a WRITE statement 
containing this option, the "event 
variable" is made active (that is, it 
cannot be associated with another 
event) and is given the completion 
value • O'B, provided that the UNDE- 
FINEDFILE condition is not raised by 
an implicit file opening (see "Note" 
below) . The event variable remains 
active and retains its ' O'B completion 
value until control reaches a WAIT 
statement specifying that event vari- 
able. At this time, either of the 
following can occur: 

a. If the WRITE statement has been 
executed successfully and none of 
the conditions TRANSMIT, KEY, or 
RECORD has been raised as a result 
of the WRITE, the event variable 
is set complete (given the comple- 
tion value ' l'B), and the event 
variable is made inactive, that 
is, it can be associated with 
another event. 

b. If the WRITE statement has 
resulted in the raising of TRANS- 
MIT, KEY, or RECORD, tne interrup- 
tion for each of these conditions 
does not occur until the WAIT is 
encountered. At such time, the 
corresponding on-units (if any) 
are entered in the order in which 
the conditions were raised. After 
a return from the final on- unit, 
or if one of the on-units is ter- 
minated by a GO TO statement, the 
event variable is given the com- 
pletion value ('l'B) and is made 
inactive. 

If the variable in the FROM or INTO 
option is a structure, it cannot con- 
tain VARYING strings. However it is 
possible to have a VARYING string ele- 
ment variable in these options. This 
is an implementation restriction. 

Note : If the WRITE statement causes 
an implicit file opening that results 
in the raising of UNDEFINEDFILE, the 
on-unit associated with this condition 



is entered immediately and the event 
variable remains unchanged,* that is, 
the event variable remains inactive 
and retains the same value it had when 
the WRITE was encountered. If the 
on-unit does not correct the condi- 
tion, then, upon normal return from 
the on-unit, the ERROR condition is 
raised; if the condition is ccrrected 
in the on-unit, that is, if the file 
is opened successfully, then upon 
normal return from the on-unit, the 
event variable is set to ' O'B, it is 
made active, and execution of the 
WRITE statement continues. 



PREPROCESSOR STATEMENTS 

All of the statements that can be 
executed at the preprocessor stage are pre- 
sented alphabetically in this section. 

The %ACTIVATE Statement 

Function: 

The appearance of an identifier in a 
%ACTIVATE statement makes it active and 
eligible for replacement; that is, any sub- 
sequent encounter of that identifier in a 
nonpreprocessor statement, while the iden- 
tifier is active, will initiate replacement 
activity. 

General format: 

%[ label:)... ACTIVATE identifier 
[ , identifier] . . . ; 

Syntax rules: 

1. Each identifier must be either a pre- 
processor variable or a preprocessor 
procedure name. 

2. A %ACTIVATE statement cannot appear 
within a preprocessor procedure. 

General rules: 

1. An identifier cannot be activated ini- 
tially by a ^ACTIVATE statement; the 
appearance of that identifier in a 
%DECLARE statement serves that pur- 
pose. An identifier can be activated 
by a %ACTIVATE statement only after it 
has been deactivated by a %DEACTIVATE 
statement. 

2. When an identifier is active (and has 
been given a value — if it is a pre- 
processor variable) any encounter of 
that identifier within a nonpreproces- 
sor statement will initiate replace- 
ment activity in all cases except when 
the identifier appears within a com- 
ment or within apostrophes. 
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Example: 



The %DE ACTIVATE Statement 



If the source program contains the fol- 
lowing sequence of statements: 

% DECLARE I FIXED, T CHARACTER; 

% DE ACT' IV ATE I; 

% I = 15; 

% T = ' A(I)'; 

S = I*T*3; 

% I = 1+5; 

% ACTIVATE I; 

% DEACTIVATE T; 

R = I*T*2; 

then the preprocessed text generated by the 
above would be as follows (replacement 
blanks are not shown) : 

S = I*A(I)*3; 

R = 20*T*2; 

The % Assignment Statement 

Function: 

The % assignment statement is used to 
evaluate preprocessor expressions and to 
assign the result to a preprocessor 

variable. 



General format: 



%[ label:], 



General rule: 



preprocessor-variable = 
preprocessor-expression; 



When the value assigned to a preproces- 
sor variable is a character string, this 
character string should not contain a pre- 
processor statement, nor should it contain 
unmatched comment or string delimiters. 



Function: 

The appearance of an identifier in a 
%DEACTIVATE statement makes it inactive and 
ineligible for replacement; that is, any 
subsequent encounter of that identifier in 
a nonpreprocessor statement will net initi- 
ate any replacement activity (unless, of 
course, the identifier has been reactivated 
in the interim) . 

General format: 

% [label:]... DEACTIVATE identifier 
I , identifier] . . . ; 

Syntax rules: 

1. Each "identifier" must be either a 
preprocessor variable, the SUESTR 
built-in function, or a preprocessor 
procedure name. 

2. A ^DEACTIVATE statement cannot appear 
within a preprocessor procedure. 

General rule: 

The deactivation of an identifier does 
not strip it of its value, nor does it pre- 
vent it from receiving new values in subse- 
quent preprocessor statements. Deactiva- 
tion simply prevents any replacement for a 
particular identifier from taking place. 



The %DECLARE Statement 

Function: 

The ^DECLARE statement establishes an 
identifier as a preprocessor variable or a 
preprocessor procedure name and also serves 
to activate that identifier. An identifier 
nust appear in a %DECLARE statement before 
it can be used as a variable or a procedure 
name in any other preprocessor statement. 

General format: 



52. 



The general format is shown in Figure 



,% [label:] .. .DECLARE identifier {FIXED | CHARACTER | entry-declaration} 

[ , identifier [FIXED | CHARACTER ( entry-declaration) ] 
[where the format of "entry declaration" is: 



. — 1 



ENTRY [ ([CHARACTER | FIXED] 

[, [CHARACTER| FIXED] ] . 
RETURNS (CHARACTER I FIXED) 



)1 



L . „j 

Figure 52. General Format of the ^DECLARE Statement 



310 



Page of GC28-20H5t1 f Issued September 30, 1971 by TNL GN28-3185 



Syntax rules: 

1. CHARACTER or FIXED must be specified 
if the "identifier* is a preprocessor 
variable; an entry declaration roust be 
specified if the "identifier" is a 
preprocessor procedure name. 

2. Only the attributes shown in the above 
format can be specified in a ^DECLARE 
statement. 

3. Factoring of attributes is restricted 
to no more than three. 

4. Any label attached to a %DECLARE 
statement is ignored by the scan. 

General rules: 

1- No length can be specified with the 

CHARACTER attribute. If CHARACTER is 
specified, it is assumed that the 
associated identifier represents a 
varying- length character string that 
has no maximum length. 

2. A preprocessor declaration is not 
known until it has been encountered by 
the scan. If a reference to a prepro- 
cessor variable or procedure is 
encountered in a preprocessor state- 
ment before the declaration for that 
variable or procedure has been 
scanned, then the reference is in 
error. 

3. The scope of all preprocessor 
variables, procedure names, and labels 
is the entire source program scanned 
by the preprocessor, not including any 
preprocessor procedures that redeclare 
such identifiers. The scope of a 
declaration in a preprocessor proce- 
dure is limited to that procedure. 

4. An entry declaration must be specified 
for each preprocessor procedure in the 
source program. The ENTRY attribute 
specifies the number (and attributes, 
if desired) of the parameters of the 
procedure; the RETURNS attribute spe- 
cifies the attribute of the value 
returned by that procedure. 

The ENTRY attribute in the entry 
declaration must account for every pa- 
rameter specified in the %PROCEDURE 
statement of the preprocessor proce- 
dure. If the procedure has no parame- 
ters, ENTRY must be specified without 
the parenthesized list following,* if 
the procedure has one parameter, ENTRY 
followed by empty closed parentheses - 
- ENTRY C) — will suffice; if the 
procedure has more than one parameter, 
the place of each additional parameter 
must be kept by a comma. Thus, ENTRY 



(,, FIXED) specifies three parameters, 
the third of which has the attribute 
FIXED; the preprocessor makes no 
assumptions about the attributes of 
the first two. 

The RETURNS attribute specifies the 
attribute of the value to be returned 
by the preprocessor procedure to the 
point of invocation. If, in fact, the 
attribute of the value does not agree 
with the attribute specified by 
RETURNS, no conversion is performed 
and errors may result. 

See "Preprocessor Procedures" in Part 
I f Section 16, "Compile-Time Facili- 
ties," for a discussion of the above 
attributes, as well as a discussion of 
the association of arguments and para- 
meters at the time of invocation. 

5. After a ^DECLARE statement has been 
executed, it is replaced by a null 
statement so that any subsequent scan- 
ning through the statement has no 
effect. 

The %DO Statement 

Function: 

The %DO statement is used in conjunction 
with a %END statement to delimit a prepro- 
cessor DO-group. It cannot be used in any 
other way. 



General format: 



% [label:] ...DO 



i= = ml 



"(TO m2 IBY m3] | 
I BY m3 CTO m2) ) 



% Syntax rule: 



The "i" represents a preprocessor vari- 
able, and "ml," "m2," and "m3" are prepro- 
cessor expressions. 

General rule: 

The expansion of a preprocessor DO-group 
is the same as the expansion for a corre- 
sponding nonpreprocessor DO-group and "i," 
"ml," "m2," and "m3" have the same meaning 
that the corresponding expressions in a 
nonpreprocessor DO-group have. 

See "Preprocessor DO-Groups" in Part I, 
Section 16, "Compile-Time Facilities," for 
a discussion and an example of its use. 

The XENP Statement 

Function: 

The %END statement is used in conjunc- 
tion with %DO or %PROCEDURE statements to 
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delimit preprocessor LO-groups or prepro- 
cessor procedures. 

General format:: 

% [label:!... END (label J ; 

Syntax rule: 

The label following END roust be a label 
of a %PBOCEDURt or %W statement. Multiple 
closure is permitted. 

The %GO TO Sta t ement 

Function: 

The %GO TO statement causes the prepro- 
cessor to continue its scan at the speci- 
fied label* 

Gfnf;i*ai format: 

% [label;]... (GO TO (GOTO! label; 

General rules; 

1. The label following the keyword GO TO 
determines the point to which the scan 

will he transferred. It must be a 
label of a preprocessor statement, 
although it cannot be the label of a 

preprocessor procedure. 

2. A preprocessor GO TO statement appear- 
ing within a preprocessor procedure 
cannot transfer control to a point 
outside of that procedure. In other 
words, the label following GO TO roust 
be contained within the procedure. 

3. See "The X1NCLUDE Statement* for a 

restriction regarding the use of %G0 

TO with included text. 

The %IF Statement 



Function: 

The %1F statement can control the flow 
of the scan according to the value of a 

preprocessor expression. 

General format: 

%t label:] . . . IF preprocessor-expression 
%TBEN preprocessor-clause-1 
If ELSE preprocessor-clause- 2} 

Syntax rule: 

A preprocessor clause is any single pre- 
processor statement other than %DECLAHE, 
%PROCEDURE, %EHD S or %DO (percent symbol 
included) or a preprocessor DO-group (per- 
cent symbols included) . Otherwise, the 



syntax is the same as that for non- 
preprocessor IF statements. 

General rules: 

1. The preprocessor expression is eva- 
luated and converted to a bit string 

(if the conversion cannot be made, it 
is an error). If any bit in the str- 
ing has the value 1, clause-1 is 
executed and clause-2, if present, is 
ignored; if all bits are 0, ciause-1 
is ignored and ciause-2, if present, 
is executed- In either case, the scan 
resumes immediately following the IF 
statement, unless, of course, a %GO TO 
in one of the clauses causes the scan 
to resume elsewhere. 

2. %IP statements can be nested according 
to the rules for nesting nonpreproces- 
sor IF statements. 



The * INCLUDE Statement 

Function: 

The %INCL0DE statement is used to 
include (incorporate) strings of external 
text into the source program being scanned. 
This included text can contribute to the 

preprocessed text being formed. 

General format: 

The %INCLUDE statement is defined as 
follows for the TSS/360 PL/I compiler; 



%llafcel:l . 



INCLUDE 



| ddnaire- 1 C member— name- 1 ) | 
f meirber-name- 1 I 

| f ddname~"2 (member- name- 2) | 
f , member- name- 2 J. 



Syntax rule 



!M,ch "ddname" and "member name* pair 
identifies the external text to be 
incorporated into the source program* 
This external text must be a member of 
a partitioned data set. 

A "ddname - specifies the ddname occur- 
ring in the name field of the appro- 
priate DDEF command * Its associated 
"meirber name* specifies the name of 
the data set member to be inco- 
rporated. If •ddname* is omitted, 
5YSULIB is assumed, and no DDEF com- 
mand is required. 

A % INCLUDE statement cannot be used in 
a preprocessor procedure* 
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General rules; 



The % Null Statement 



1. Included text can contain nonprepro- 
cessor and/or preprocessor statements, 



The included text is scanned, in 
sequence, in the same manner as the 
source program; that is, preprocessor 
statements are executed and replace- 
ments are made where required. 



Function: 

The % null statement can be used to pro- 
vide transfer targets for %GO TO state- 
ments. It is also useful for balancing 
ELSE clauses in nested %IF statements. 

General format: 

% [label:) ; 



3. ^INCLUDE statements can be nested. In 
other words, included text also can 
contain %INCLUDE statements. A %GO TO 
statement in included text can transf- 
er control to a point in the source 
program or in any included text at an 
outer level of nesting, but the 
reverse is not permitted. An analo- 
gous situation exists for nested DO- 
groups that specify iterative execu- 
tion: control can be transferred from 
an inner group to an outer, containing 
group, but not from an outer group 
into an inner, contained group. 

4. Preprocessor statements in included 
text must be complete. It is not per- 
missible, for example, to have half of 
a %I¥ statement in included text and 
half in the other part of the source 
program. 

Example: 

If the source program contained the fol- 
lowing sequence of statements: 

^DECLARE (FILENAME!, FI1ENAME2) 
CHARACTER; 

% FILENAMEl = • MASTER'; 

% FILENAME2 = , NEWFILE f ; 

% INCLUDE DCLS; 

and if the SYSULIB member name DCLS 
contained: 

DECLARE (FILENAME!, FILENAME2) 
FILE RECORD INPUT 
DIRECT KEYED; 

then the following would be inserted into 
the preprocessed text: 

DECLARE (MASTER, NEWFILE) 
FILE RECORD INPUT 
DIRECT KEYED; 

Note that this is a way in which a 
central library of file declarations can be 
used, with each user supplying his own 
names for the files being declared. 



The ^PROCEDURE Statement 

Function: 

The %PRCCEDURE statement is used in con- 
junction with a %END statement to delimit a 
preprocessor procedure. Such a preproces- 
sor procedure is an internal function pro- 
cedure that can be executed only at the 
preprocessor stage. 

General format: 

% label: [label:]... PROCEDURE 

[(identifier [, identifier]...)) 

•RETURNS (CHARACTER | FIXED) ■ ; 

Syntax rules: 

1. Each "identifier" is a parameter of 
the function procedure. 

2. One of the RETURNS attributes CHARACT- 
ER or FIXED must be specified to ind- 
icate the type of value returned by 
the function procedure. There can be 
no default. 

General rules: 

1. The only statements and groups that 

can be used within a preprocessor pro- 
cedure are: 

a. the preprocessor assignment 
statement 

b. the preprocessor DECLARE statement 

c. the preprocessor DO-group 

d. the preprocessor GO TO statement 

e. the preprocessor IF statement 

f . the preprocessor null statement 

g. the preprocessor RETURN statement 

All of these statements and the DO- 
group must adhere to the syntax and 
genera! rules given for them in this 
section, with one exception; all per- 
cent symbols must be omitted . 
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2. A GO TO statement appearing in a pre- 
processor procedure cannot transfer 
control to a point outside of that 
procedure. 

3- As implied by general rule 1, prepro- 
cessor procedures cannot be nested. 

4. A preprocessor procedure can be 
invoked by a function reference in a 
preprocessor statement, or, if the 
function procedure name is active, by 
the encounter of that name in a non- 
preprocessor statement. 

5. For the TSS/36C compiler, there may be 
no more than 2SU compile-time proce- 
dures per compilation. Further, each 
procedure is limited to a maximum of 
15 parameters. 

The Preprocessor RETURN Statement 

Function: 

The preprocessor RETURN statement can be 
used only in a preprocessor procedure and, 



therefore, can have no leading %. It 
returns a value as well as control back to 
the point from which the preprocessor pro- 
cedure was invoked. 



General format: 

(label:)... RETURN 

(preprocessor-expression) ; 

General rule: 

The value of the preprocessor expression 
is converted to the attribute specified in 
the ^PROCEDURE statement before it is 
passed back to the point of invocation. If 
the point of invocation is in a nonprepro- 
cessor statement, replacement activity can 
be performed on the returned value after 
that value has replaced the procedure 
reference. 

Note that the rules for preprocessor 
expressions do not permit the value 
returned by a preprocessor procedure to 
contain preprocessor statements. 
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SECTION 11: 



DATA NAPPING 



This section describes structure mapping 
and alignment of records in buffers as per- 
formed by the TSS/360 PL/I compiler. The 
information is included in this manual 
because, under certain circumstances, it 
should be borne in mind while the program 
is being written. However, the information 
is not essential to stream-oriented trans- 
mission or unaligned data; it is intended 
for those using record-oriented transmis- 
sion (particularly locate mode) with 
aligned structures. 



STRUCTURE MAPPING 

For any structure (major or minor), the 
length, alignment requirement, and position 
relative to a doubleword boundary will 
depend on the lengths, alignment require- 
ments, and relative positions of its mem- 
bers. The process of determining these 
requirements for each level in turn and 
finally for the complete structure, is 
known as structure mapping . 

During the structure mapping process, 
the compiler minimizes the amount of unused 
storage (padding) between members of the 
structure. It completes the entire process 
before the structure is allocated, accord- 
ing (in effect) to the rules discussed in 
the following paragraphs. It is necessary 
for the user to understand these rules for 
such purposes as determining the record 
length required for a structure when 
record-oriented input/output is used, and 
for determining the amount of padding or 
rearrangement required to ensure correct 
alignment of a structure for locate-mode 
input/output (see "Record Alignment," 
below) . 



another unit, and so on until the complete 
structure has been mapped. The rules for 
the process are therefore categorized as: 

Rules for determining the order of 
pairing 

Rules for mapping one pair 

These rules are described below, and are 
followed by an example showing an applica- 
tion of the rules in detail. 



Notes 



To follow these rules, it is neces- 



sary to appreciate the difference between 
logical level and level number . The item 
with the greatest level number is not 
necessarily the item with the deepest log- 
ical level. If the structure declaration 
is written with consistent level numbers or 
suitable indention (as in the detailed 
example given after the rules) , the logical 
levels are immediately apparent. In any 
case, the logical level of each itenr in the 
structure can be determined by applying the 
following rule to each item in turn, start- 
ing at the beginning of the structure 
declaration : 

The logical level of a given item is 
always one unit deeper than that of the 
nearest preceding item that has a less- 
er level number than the given item. 

For example: 

CCL 1 A, U B, 5 C, 5 D, 3 E, 8 F, 7 G; 

12 3 3 2 3 3 

The lower line shows the logical level 
for each item in the declaration. 



Structure mapping is not a physical pro- 
cess. Although during this discussion such 
terms as "shifted" and "offset" are used, 
these terms are used purely for ease of 
discussion, and do not imply actual move- 
ment in storage; when the structure is 
allocated, the relative locations are al- 
ready known as a result of the mapping 
process. 



RULES 

The mapping for a complete structure 
reduces to successively combining pairs of 
items (elements, or minor structures whose 
individual mappings have already been 
determined). Once a pair has been com- 
bined, it becomes a unit to be paired with 



Rules for Order of Pairing 

The steps in determining the order of 
pairing are as follows: 

1. Find the minor structure with the 
deepest logical level (which we will 
call logical level n) . 

2. If the number of minor structures at 
logical level n exceeds one, take the 
first one of them as it appears in the 
declaration. 

3. Using the rules for mapping one pair 
(see below), pair the first twc ele- 
ments appearing in this minor struc- 
ture, thus forming a unit. 
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4. Pair this unit with the next element 
(if any) appearing in the declaration 
for the minor structure, thus forming 
a larger unit. 

5. Repeat rule *4 until all the elements 
in the minor structure have been com- 
bined into one unit. This completes 
the mapping for this minor structure; 
its alignment requirement and length, 
including any padding, are now deter- 
mined and will not change (unless the 
programmer changes the structure 
declaration) . Its offset from a doub- 
leword boundary will also have been 
determined; note that this offset will 
be significant during mapping of any 
containing structure, and it may 
change as a result of such mapping. 

6. Repeat rules 3 through 5 for the next 
minor structure (if any) appearing at 
logical level n in the declaration. 

7. Repeat rule 6 until all minor struc- 
tures at logical level n have been 
mapped. Each of these minor struc- 
tures can now be thought of as an ele- 
ment for structure mapping purposes. 

8. Repeat the process for minor struc- 
tures at the next higher logical 
level; that is, make n equal to (n - 
1) and repeat rules 2 through 7. 

9. Repeat rule 8 until ( = 1; then repeat 
rules 3 through 5 for the major 
structure. 

Rules for Mapping One Pair 

As stated earlier, terms apparently im- 
plying physical storage are used here only 
for ease of discussion; the storage thus 
implied may be thought of as an imaginary 
model consisting of a number of contiguous 
doublewords. Each doubleword has eight 
bytes numbered zero through 7, so that the 
offset from a doubleword boundary can be 
given; in addition, the bytes in the model 
may be numbered continuously from zero 
onwards, starting at any byte, so that 
lengths and offsets from the start of a 
structure can be given. 

1. Begin the first item of the pair on a 
doubleword boundary; or, if the item 
is a minor structure that has already 
been mapped, offset it from the doub- 
leword boundary by the amount 
indicated. 

2. Begin the other item of the pair at 
the first valid position following the 



end of the first item. This position 
will depend on the alignment require- 
ment of the second item. Alignment 
and length requirements for elements 
are given in Figures 53 and 54. (If 
the item is a minor structure, its 
alignment requirement will have been 
determined already.) 



3. Shift the first item towards the 

second item as far as the alignment 
requirement of the first item will 
allow. The amount of shift determines 
the offset of this pair from a double- 
word boundary. 

After this process has been completed, 
any padding between the two items will have 
been minimized and will remain unchanged 
throughout the rest of the operation. The 
pair can now be considered to be a unit of 
fixed length and alignment requirement; its 
length is the sum of the two lengths plus 
padding, and its alignment requirement is 
the higher of the two alignment require- 
ments (if they differ) . 



Effect of UNALIGNED Attribute 

The example of structure mapping given 
below shows the rules applied to a struc- 
ture declared ALIGNED, because mapping of 
aligned structures is more complex owing to 
the number of different alignment require- 
ments. Briefly, with the TSS/360 PL/I com- 
piler, the general effect of the UNALIGNED 
attribute is to reduce fullword and double- 
word alignment requirements down to byte, 
and to reduce the alignment requirement for 
tit strings from byte down to bit. The 
same structure mapping rules apply, but the 
reduced alignment requirements are used. 
This means that unused storage between 
items can only be bit padding within a 
byte, and never a complete byte; bit pad- 
ding may occur when the structure contains 
tit strings. 

POINTER, OFFSET, LABEL, TASK, EVENT, and 
AREA data cannot be unaligned, then 
UNALIGNED is ignored for that element; the 
element is aligned by the compiler and 
error message IEW3181I is put out. For 
example, in a program with the declaration 

DECLARE 1 A UNALIGNED, 
2 B, 
2 C AREAC100) ; 

C is given the attribute ALIGNED, as the 
inherited attribute UNALIGNED conflicts 
with AREA. 
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In- 



variable 
Type 



Stored Internally 
as 



Storage 
Requirements 
(in Bytes) 



Alignment 
Requirements 



Explanation 



BIT (n) 



h 



One byte for each 
groups of 8 bits 
Cor part thereof) 



CEIL(n/8) 



CHARACTER (n) 



One byte per 
character 



PICTURE 



One byte for each 
PICTURE character 
(except M,V,K f G) 



Number of PICTURE 
characters other 
than M f V,K, and G 



Data may begin 
on any byte 
through 7 



DECIMAL FIXED (p,q) 



1/2 byte per 
digit plus 1/2 
byte for sign 



CEILC (p+l)/2) 



BINARY FIXED (p,q) 
p < 16 



Binary integer 



Halfword 



Data may begin 
on byte 0,2, 4, 
or 6 



BINARY FIXED (p f q) 
p > 16 



Binary integer 



BINARY FLOAT (p) 
p < 22 



DECIMAL FLOAT (p) 

P < 7 



H 



Short floating 
point 



Fullword 



Data may begin 
on byte 
or U only 



POINTER 

OFFSET 



LABEL 

TASK 

EVENT 



8 
28 
32 



BINARY FLOAT (p) 
21 < p < 5a 



DECIMAL FLOAT (p) 
6 < p < 17 



H 



Long floating 
point 



Double^ord 



Data may begin 
on byte only 



AREA 



116+size 



Note : The term CEIL used in some storage calculations has the same meaning as the 
CEIL built-in function of PL/I, i.e., the smallest integer that exceeds the 
value of the expression in parentheses; thus, CEXLC30/8) =4. 

i . . . . 

Figure 53, Summary of Alignment Requirements for ALIGNED Data ^ 
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Variable 
Type 



Stored Internally 
as 



Storage 
Requirements 
(in Bytes) 



Alignment 
Requirements 



+- 



Explanation 



BIT (n) 



As many bits as 
are required, 
regardless of 
byte boundaries 



n bits 



Bit 



Data may begin 
on any bit in 
any byte 
through 7 



CHARACTER (n) 



One byte per 
character 



h 



PICTURE 



h 



One byte for each 
PICTURE character 
(except M,V,K,G) 



Number cf PICTURE 
characters other 
than M,V,K and G 



DECIMAL FIXED (p,q> 



1/2 byte per 
digit, plus 1/2 
byte for sign 



CEIL( (p+l)/2) 



BINARY FIXED (p,q> 
p < 16 



Binary integer 



BINARY FIXED (p,q) 
p > 16 



Binary integer 



Byte 



BINARY FLOAT (p) 
p < 22 



DECIMAL FLOAT (p) 
p < 7 



Short 
floating point 



BINARY FLOAT (p) 
21 < p < 54 



DECIMAL FLOAT (p) 
6 < p < 17 



Long 

floating point 



Data may begin 
on any byte 
through 7 



j. — — 

INote: 

L 


POINTER, 


X 

v OFFSET, 


LABEL, 


TASK, 


-X . 

EVENT, 


J. X _ 

and AREA data cannot be UNALIGNED. 



Figure 54. Summary of Alignment Requirements for UNALIGNED Data 



EXAMPLE OF STRUCTURE MAPPING 

This example shows the application of 
the structure mapping rules for a structure 
declared as follows: 

DECLARE 1 A ALIGNED, 

2 B POINTER, 
2 C, 

3 D FLCAT DECIMAL(14), 
3 E, 

4 F LABEL, 

5 H CHARACTER (2), 

5 I FLOAT DECIMAL(13), 

J FIXED BINARY ( 31, 0) , 

CHARACTER (2) , 

FIXED BINARY(20,0), 



4 
K 
L 



3 
3 

3 N, 

4 P FIXED BINARY, 
4 Q CHARACTER (5) , 



4 R FLOAT DECIMAL (2), 

S, 

4 T FLOAT DECIMAL (15), 

4 U BIT (3) , 

4 V CHAR(l), 

W POINTER 

PICTURE , $9V99 f ; 



The minor structure at the deepest log- 
ical level is G, so that this is mapped 
first. Then E is mapped, followed by N, S, 
C, and M, in that order. Finally, the 
major structure A is mapped. For each 
structure, a table is given showing the 
steps in the process, accompanied by a dia- 
gram giving a visual interpretation of the 
process. At the end of the example, the 
structure map for A is set out in the form 
of a table showing the offset of each memb- 
er from the start of A. 
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Step 1 
Step 2 



Name of 
Item 



H 
I 



Alignment 
Requirement 



+- 



Byte 
Double 



*H | Double 
I J Double 

G | Double 



T — . 1 

Offset from G 



T T 

(Offset from | 
Length | Doubleword (Length cf 

j._ T ^ Padding 

I Begin | End | 








2 I 6 I 7 I | 

8 | | 7 | | 2 

| 10 I 6 | 7 | | • | 

— X X X X X _. J 



♦First item shifted right 
H I 



*T~T-T-"T-T-T-T-T-T-T-T-T~T-T-T-T~T~T*-T-T-T~T""T~T"-T-T-T-T~T~T-T-T-"r- 

Step 1 |0|1|2|3|4|5|6|7|0|1|2|3|U|5|6|7|0|1|2|3|H|5|6|7|0|1|.2|3|4|5|6|7|0 

^_X--X_X_X_X_X_X^._X_X_X_X_X_X_X-X_X_X_X_X_X_X_X_X..X-X_X--J 



_X_X_X_X_X_X_X-X.-X_X_X_X--X_X_X-. 



. t _x_x_x_,_ 



— T-T-l — T-T-T-T-T-T-T-T-T~T'-T-T-T-T-T"'T-T~T"T-T-T"T-T-T-T-T-T-T-r~1— 

Step 2 |0|l|2|3|4|5|6|7|0|l|2|3|4|5|6|7|0|l|2|3|i4|5|6|7|0|l|2|3|4|5|6|7|0 

^-X_X-X-X_X-X_X-|-X_X-X-X--X-X-X-^-.X-X-X-.X-.X-.X-X-|-X-.X-.X-X-.X-X-X_.J 

I ' I l I I I ' I 



Figure 55. Mapping of Minor Structure G 



Section 11: Data Mapping 319 • 



Step 1 
Step 2 
Step 3 



(Begin | End 



Name of 
Item 



F 
G 

F 
G 

F 

through 

G 

J 



Alignment 
Requirement 



Word 
Double 

Word 
Double 



Double 



Word 



Length 



T T 

Offset from 
Doubleword 



h 



8 

10 

8 

10 



20 



Length of 
4 Padding 




6 

6 



7 
7 

3 
7 



T 1 

Offset from G 








10 



20 



| E | Double 1 24 | 4 | 3 | | | 

L X X, X: X X X J 

♦First item shifted right 

F G 

-T-T-T-T-T-T-T-T-T-T-T-T-T-*T-T-T-T-T-T-T-T-T~T-T""T"T-T" , T-T-T-T"T""l" to 

Step 1 |0|l|2|3lH|5|6|7|0|l|2|3|a|5|6|7|0|l|2|3|a|5|6|7|0|l|2|3|il|5|6|7|0 
^.X-X^X-X-X-X«X-X-X«X-X^X-X_X-X.X_X-.X-X-i.-X-X-X-|-.X-X-X-i-X-X-X-J-_ 

III I ' I 



_ T ~ T _ T _ T _ T _ T _ T _ T _ T _ T _ T _ T _„ 

Step 2 |0|1|2|3|4|5|6|7|0|1|2|3|- 
^_x_x_x_x_x_x_x_j_x_x_x_i^ 

I ( I ! 



^6|7|0|l|2|3|«l|5|6|7|0|l|2|3|4|5|6|7|0 
-X-i_X_X_X_X_X_X_X-4_X-X_X-X-X_X-.X-.X-_. 

I ' I ' I 



Step 3 
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Figure 57, Mapping of Minor Strucrure N 
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Figure 59. Mapping of Minor Structure c 
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Figure 61. Mapping of Major Structure A 
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Figure 62. Offsets in Final Mapping of* 
Structure A 



RECORD ALIGNMENT 

The user must pay attention to record 
alignment within the buffer when using lo- 
cate mode input/ out put . The first data 
byte of the first record in a block is gen- 
erally aligned in a buffer on a doubleword 
boundary (see Figure 66) ; the next record 
begins at the next available byte in the 
buffer. The user roust ensure that the 
alignment of this byte matches the align- 
ment requirements of the based variable 
with which the record is to be associated. 

Most of the alignment problems described 
here occur in ALIGNED tased or nonbased 
variables. If these variables were 
UNALIGNED, the preservation of the record 
alignment in the buffer would be consi- 
derably easier. 



If a VB-format record is to be con- 
structed with logical records defined by 
the structure: 

1 S, 

2 A CHAR(l), 

2 B FIXED BINARY (31,0) ; 

this structure is mapped as in Figure 63. 
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W = Word boundary 

Figure 63. Format of Structure S 



If the block was created using a 
sequence of WRITE FROM (S) statements, the 
format of the block would be as in Figure 
64 f and it can be seen that the alignment 
in the buffer differs from the aliqnrrent of 
S. 

There is no problem if the file is then 
read using move mode READ statements, e.g., 
READ INTO(S), because information is moved 
from the buffer to correctly aligned 
storage. 

If, however, a structure is defined as: 

1 SBASED BASED (P) LIKE S; 

and READ SET(P) statements are used, 
reference to SBASED. B will, for the first 
record in the block, be to data aligned at 
a doubleword plus one byte, and will pro- 
bably result in a specification 
interruption. 

The same problem would have arisen had 
the file originally been created by using 
the statement : 

LOCATE SBASED SETCP) ; 

Again, for the first record in the 
block, P would be set to address a double- 
word and references to SBASED. B would be 
invalid. 



r 




T~ 




T T™ 




T 




--— T T 




T 


I 


BL 


1 


RL 


|A | 


B 


1 


RL 


|A i 


B 


1 


i 




X 




X X 




X 




X X 




X ., . 



c t 

D W 

BL = Block length 
RL = Record length 



D 



W 



t 

D 



t 
W 



D = Doubleword boundary 
W = Word boundary 



Figure 64. Block Created from Structure S 
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BL = Block length 
RL = Record length 



D = Doubleword boundary 
W = Word boundary 



Figure 65. Block Created by Structure S With Correct Alignment 



In both cases the problem is avoided if 
the structure is padded in such a way that 
B is always correctly aligned: 

1 S, 

2 PAD CHAR (3), 

2 A CHAR CI) , 

2 B FIXED BINARY; 

The block format would now be as in Figure 
65; B is always on a word boundary. Pad- 
ding may be required at the beginning and 
end of a structure to preserve alignment. 

The alignment of different types of rec- 
ord within a buffer is shown in Figure 66. 
For all organizations and record types 
except blocked records in INDEXED data sets 
1 with forma t-FB f -V, or -VB records and 
RKP=0, the first data byte in a block is 
always on a doubleword boundary. The posi- 
tion of any successive records in the buff- 
er depends on the record format. 

For unblocked INDEXED with format- F and 
RKP=0, the LOCATE statement will use a hid- 
den buffer if the data set key length is 
not a multiple of 8. The pointer variable 
will point at this hidden buffer. 

A special problem arises when using lo- 
cate mode I/O in conjunction with based 
variable containing adjustable extents, 
i.e., containing a REFER option. Consider 
the following structure: 

1 S BASED (P), 
2 N f 
2 C CHAR CL REFER (N> ) ; 

If it is desired to create blocked format-V 
records of this type, using locate mode 
I/O f record alignment must be such that N 



is half word aligned. If L is not a mul- 
tiple of 2 then, if the alignment of the 
current record is correct, that of the fol- 
lowing record will be incorrect. Correct 
alignment can be obtained by the following 
sequence: 



LENGTH = L; 

/* SAVE DESIRED LENGTH L */ 
| L = 2*CEIL(L/2>; 

I /* ROUND UP TO MULTIPLE OF 2 */ 

LOCATE S FILE (F> ; 
N = LENGTH; 

/* SET REFER VARIABLE */ 

This technique can be adapted to other uses 
of the REFER option. 

The preprocessor RETURN statement can be 
used only in a preprocessor procedure and, 
therefore, can have no leading %. It 
returns a value as well as control back to 
the point from which the preprocessor pro- 
cedure was invoked. 

General format: 

[label:]... RETURN 

(preprocessor-expression) ; 



General rule: 

The value of the preprocessor expression 
is converted to the attribute specified in 
the ^PROCEDURE statement before it is 
passed back to the point of invocation. If 
the point of invocation is in a nonprepro- 
cessor statement, replacement activity can 
be performed on the returned value after 
that value has replaced the procedure 
reference. 
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Each VBS record is moved to a hidden buffer 



2. Control bytes and key for the first data item have been omitted where they 
precede the doubleword alignment 

•Figure 66. Alignment of Data in a Buffer in Locate Mode Input/Output, for Different For- 
mats and Data Set Organizations 
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SECTION 12; DEFINITIONS OF TERMS 



This section provides definitions for 
most of the terms used in this publication. 

access : the act that encompasses the 
reference to and retrieval of data. 

action specification : in an ON statement, 
the on-unit or the single keyword SYSTEM, 
either of which specifies the action to be 
taken whenever an interruption results from 
raising of the named condition. 

activation : institution of execution of a 
block. A procedure blcck is activated when 
it is invoked at any of its entry points; a 
begin block is activated when it is encoun- 
tered in normal sequential flow. 

active : 

1. the state in wnich a block is said to 
be after activation and before 
termination. 

2. the state in which a preprocessor 
variable or preprocessor procedure is 
said to be when its value can replace 
the corresponding identifier in source 
program text. 

3. the state in which an event variable 
is said to be as a result of its 
appearance in the EVENT option of an 
executed RECORD input/output state- 
ment. An event variable remains 
active, and, hence, cannot be asso- 
ciated with any other input/output 
operation, until a WAIT statement nam- 
ing that event variable has been 
executed. 



additive attributes; 



file attributes for 



which there are no defaults and which, if 
required, roust always be stated explicitly. 

address : a specific storage location at 
which a data item can be stored. 

adjustable (bounds and lengths) : bounds or 
lengths that may be different for different 
allocations of the associated variable. 
Adjustable bounds and lengths are specified 
as variables, expressions, or asterisks, 
which are evaluated separately at each 
allocation. They cannot be used for STATIC 
data. 

allocated variable : a variable with which 
storage has been associated. 

allocation : the association of storage 
with a variable. 



alphabetic character : any of the charac- 
ters A through Z and the alphabetic exten- 
ders #, $, and a. 



alphameric character : an alphabetic 
character or a digit. 

alternative attributes : attributes that 
may be chosen from groups of two or more 
alternatives. If none is specified, a 
default is assumed. 

area : a block of storage defined by an 
area variable and reserved, on allocation, 
for the allocation of based variables. 

arithmetic conversion : the transformation 
of a value from one arithmetic representa- 
tion to another arithmetic representation. 

argument : an expression, file name, state- 
ment label constant or variable, mathemat- 
ical built-in function name, or entry name 
passed to an invoked procedure as part of 
the procedure reference. 

arithmetic data : data that has the charac- 
teristics of base, scale, mode, and preci- 
sion. It includes coded arithmetic data 
and numeric character data. 

arithmetic operators : any of the prefix 
operators, + and -, or the infix operators 
*» "t *, /r and **. 

array : a named, ordered collection of data 
elements, all of which have identical 
attributes. An array has dimensions, and 
elements that are identified by subscripts. 
An array can also be an ordered collection 
of identical structures. 

array of structures : an ordered collection 
of structures formed by giving the dimen- 
sion attribute to the name of a structure. 

assignment : giving a value to a variable. 

asynchronous : the overlap of an input/ 
output. operation with the execution of 
statements. 

attribute : a descriptive property asso- 
ciated with a name or expression to 
describe a characteristic of data items, of 
a file, or of an entry point the nanse may 
represent. 

automatic storag e: storage that is allo- 
cated at the accivation of a block and 
released at the termination of that block. 
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base: the number system in terms of which 
an arithmetic value is represented. In 
PL/I, the base is binary or decimal. 

based storage : storage whose allocation 
and release is controlled by the user, with 
immediate access to all unfreed 
allocations. 

begin block ; a collection of statements 
headed by a BEGIN statement and ended by an 
END statement that delimits the scope of 
names and, in general, is activated by 
normal sequential statement flow. It con- 
trols the allocation and freeing of auto- 
matic storage declared in that block. 



binary : 
value 2. 



the number system based on the 



bit : a binary digit, either or 1. 

bit string : a string composed of zero or 
more bits. 

bit-string operators : the operators 
•j (not) , £(and) f and | (or) . 

block: a begin block or a procedure block. 

bounds : the upper and lower limits of an 
array dimension. 

buffer : an intermediate area, used in 
input/output operations, into which a rec- 
ord is read during input and from which a 
record is written during output. 



call : the invocation of a subroutine by 
means of the CALL statement or the CALL 
option of the INITIAL attribute. 

character string : A string composed of 
zero or more characters from the data 
character set. 

coded arithmetic data : arithmetic data 
whose characteristics are given by the 
base, scale, mode, and precision attri- 
butes. The types for System/360 are packed 
decimal, binary fullwords, and hexadecimal 
floating-point. 



altered (preprocessed) r if desired, and 
then translated into an object program. 



compiler : a translator that converts a 
source program into an object module. It 
consists of two stages, a preprocessor and 
a processor. 



complex data : arithmetic data consisting 
of a real part and an imaginary part. 

compound statement : a statement that con- 
tains other statements. IF and ON are the 
only compound statements. 

concatenation : the operation that connects 
two strings in the order indicated, thus 
forming one string whose length is equal to 
the sum of the lengths of the two strings. 
It is specified by the operator | | . 

condition name : a language keyword that 
represents an exceptional condition that 
might arise during execution of a program. 

condition prefix : a parenthesized list of 
one or more condition names prefixed to a 
statement by a colon. It determines wheth- 
er or not the program is to be interrupted 
if one of the specified conditions occurs 
within the scope of the prefix. Condition 
names within the list are separated by 
commas . 

constant : an arithmetic or string data 
item that does not have a name; a statement 



built-in function : one of the PL/I-defined label, 
functions . 



contained in : all of the text of a block 
except any entry names of that block. (A 
label of a BEGIN statement is not contained 
in the begin block defined by that 
statement. ) 



contextual declaration: 



the association of 



attributes with an identifier according to 
the context in which the identifier 
appears. 

controlled storage : storage whose alloca- 
tion and release is controlled by the user, 
with immediate access to the latest alloca- 
tion only. 



a string of characters, used for conversion ; the transformation of a value 



comment : 

documentation, which is preceded by /* and 

terminated by */ and which is treated as a 

blank. 

comparison operators : the operators t< < 



<= 



>= 



compile time : in general, the time during 
which a source program is translated into 
an object module. In PL/ I, it is the time 
during which a source program can be 



from one representation to another. 

cross section of an array : every element 
represented by the extent of at least one 
dimension of an array. An asterisk in the 
place of a subscript in an array reference 
indicates the entire extent of that 
dimension. 

data : representation of information or of 
value. 
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data character set: 



all of those charac- 



ters whose bit configuration is recognized 
by the computer in use. 



data-directed transmissio n: the type of 
STREAM input and output in which self- 
identifying data of the type, variable-name 
= value, is transmitted. 

data ite m; a single unit of data; it is 
synonymous with "element." 



disabled: 



the state in which the occur- 



rence of a particular condition will not 
result in a program interruption. 

DO-qroup : a sequence of statements headed 
by a DO statement and closed by its corre- 
sponding END statement. 

dummy argument : a compiler-assigned vari- 
able for an argument that h?°» no user- 
assigned name or whose attributes do not 
agree with those declared with the ENTRY 
attribute for the corresponding parameter. 



edit-direct ed transmission : that type of 
STREAM transmission for which both a data 
list and a format list are specified. 

elem ent ; a single data item as opposed to 
a collection of data items, such as a stru- 
cture or an array. (Sometimes called a 

"scalar item.") 

element variable : a variable that can 
represent only a single value at any one 
point in time* 



data list : a list of expressions used in a enabled : 
STREAM input/output specification that 
represent storage areas to which data items 
are to be assigned during input or from 
which data items are to te obtained on out- 
put. (On input, the list may contain only 
variables. ) 

data set : a collection of data external to 
the program. 

data specification : the portion of a 
stream-oriented data transmission statement 
that specifies the mode of transmission 
(DATA, LIST, or EDIT) and includes the data 
list and, for edit-directed transmission, 
the format list. 

deactivated : the state in which a prepro- 
cessor variable is said to be when its 
value cannot replace the corresponding 
identifier in source program text. 

decimal : the number system based on the 
value 10. 

declaration : the association of attributes 
with an identifier explicitly, contextual- 
ly, or implicitly. 

default : the alternative assumed when an 
identifier has not been declared to have 
one of two or more alternative attributes. 

delimiter : any valid special character or 
combination of special characters used to 
separate identifiers and constants, or 
statements from one another. 

dimensionality : the number of bounds spe- 
cifications associated with an array. 



that state in which the occur- 
rence of a particular condition will result 
in a program interruption. 

entry narre : a label of a PROCEDURE or 
ENTRY statement. 

entry point : a point in a procedure at 
which it may be invoked by reference to the 
entry naire. (See p rimary entry point and 
secondary entry point . ) 

epilogue : those processes which occur at 
the termination of a block. 

event : an identifiable point in the execu- 
tion of a program. 

event n a me : the identifier used to refer 
to an event variable. 

event variable : a variable associated with 
an event; its value shows whether an event 
is complete and the status of the 
completion. 

exceptional condition : an occurrence, 
which can cause a program interruption, of 
an unexpected situation, such as an over- 
flow error, or an occurrence of an expected 
situation, such as an end of file, that, 
occurs at an unpredictable time. 

explicit declaration : the assignment of 
attributes to an identifier by means of the 
DECLARE statement, the appearance of the 
identifier as a label, or the appearance of 

the identifier in a parameter list. 

exponent (of floating-point constant) ; a 
decimal integer constant specifying the 
power to which the base of t?he floating- 
point nuirber is to be raised. 

e xpression : the representation of a value; 
examples are variables and constants 
appearing alone or in combination with 

operators, and function references. The 
term "expression" refers to an element ex- 
pression, an array expression, or a struc- 
ture expression. 

external declaration : an explicit or con- 
textual declaration of the EXTERNAL attri- 
bute for an identifier. Such an identifier 
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is known in all other blocks for which such 

a declaration exists « 



external name: an identifier which has the 



EXTERNAL attribute. 



external procedure ; a procedure that is 
not contained in any other procedure. 



field (in the data stream) : that portion 
of the data stream whose width, in number 
of characters, is defined by a single data 
or spacing format item. 

field (of a picture specification) : a 

specification or 
a numeric charac- 

that describes a 
ore than one field 
fication, they are 
factor character 

K or E exponent 
int data, or the M 
ing data. 



character-string picture 
that portion Ccr all) of 
ter picture specification 
fixed- point number. If m 
appears in a single speci 
divided by the F scaling- 
for fixed-point data, the 
character for floating-po 
field-separator for sterl 



file: a symbolic representation, within a 
program, of a data set. 

fil e name : a symbolic name used within a 
program to refer to a data set. 

format item : a specification used in edit- 
directed transmission to describe the 
representation of a data item in the stream 
or to control the format of a printed page. 



format list; 



a list of format items 



required for an edit-directed data 
specification . 

function ; a procedure that is invoked by 
the appearance of one of its entry names in 
a function reference. 

function reference : the appearance of an 
entry name in an expression, usually in 
conjunction with an argument list. 



generation (of a block) 
activation of a block. 



a particular 



generic name ; the name of a family of 
entry names. A reference to the name is 
replaced by the entry name whose entry 
attribute matches the attributes of the 
argument list. 

group : a DO-group. 

identifier : a string of alphameric and 
break characters, not contained in a com- 
ment or constant, preceded and followed by 
a delimiter and whose initial character is 
alphabetic. 

imaginary number : a number whose factors 
include the square root of -1. 

implicit declaration : association of 
attributes with an identifier used as a 
variable without having been explicitly or 
contextually declared; default attributes 
apply, depending upon the initial letter of 
the identifier. 

inactive block : a procedure or begin block 
that has not been activated or that has 
been terminated. 

inactive event variable : an event variable 
that is not currently associated with an 
event. 

infix operator : an operator that defines 
an operation between two operands. 

initial procedure : an external procedure 
whose PROCEDURE statement has the OPTIONS 
(MAIN) attribute. Every PL/I program must 
have an initial procedure. It is invoked 
automatically as the first step in the 
execution of a program. 

i nput/output : the transfer of data between 
an external medium and internal storage. 

interleaving of subscripts : a subscript 
notation used with subscripted qualified 
names that allows one or more of the 
required subscripts to immediately follow 
any of the component names. 

internal block : a block that is contained 
within another block. 



generation (of data) : a particular alloca- 
tion of controlled or automatic storage. 

generic key : a character string that iden- 
tifies a class of keys: all keys that 
begin with the string are members of that 
class. For example, the recorded keys 
'ABCD', 'ABCE*, and 'ABDF' are all members 
of the classes identified by the. generic 
keys f A f and 'AB' , and the first two are 
also members of the class 'ABC; and the 
three recorded keys can be considered to be 
unique members of the classes 'ABCD* , 
•ABCE 1 , and "ABDF f , respectively. 



internal name : an identifier that has the 
INTERNAL attribute. 

internal procedure : a procedure that is 
contained in another block. 

internal to : all of the text contained in 
a block except that text contained in 
another block. Thus the text of an inter- 
nal block (except for its entry names) is 
not internal to the containing block. 

Note : An entry name of a block is not con- 
tained in that block. 
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interruption : the suspension of normal 

program activities as the result of the 

occurrence of an enabled condition. 

invoke : to activate a procedure at one of 
its entry points; to enter an on- unit. 

invoked procedure : a procedure that has 
been activated at one of its entry points. 

invoking block : a block containing a 
statement that activates another block. 



locator variable : a variable whose value 
identifies an allocation of a based vari- 
able in storage. Pointer variables and 
offset variables are the two types of loca- 
tor variables. 

major structure : a structure whose name is 
declared with level number 1. 

minor structure : a structure whose name is 
declared with a level number greater than 
1. 



iteration factor : an expression that 
specifies: 

1. the number of consecutive elements of 
an array that are to be initialized 
with a given constant. 

2. the number of times a given format 
item or list of format items is to be 
used in succession in a format list- 



mode: real or complex designation for an 
arithmetic value. 

multiple declaration : two or more declara- 
tions of the same identifier internal to 
the same block without different qualifica- 
tions, or two or more EXTERNAL declarations 
of the same identifier as different names 
within a single program. 



key : see source key and recorded key * 

key class : a set of keys that begin with a 
common character string; this character 
string is the generic key for the class. 

keyword : an identifier that is part of the 
language and which, when used in the proper 
context, has a specific meaning to the 
compiler. 



name : 
declared. 

nesting : 

1. 



an identifier that has been 



the occurrence of a block within 
another block. 

the occurrence of a group within 
another group. 



known : a term that is used to indicate the 
scope of an identifier. For example, an 
identifier is always known in the block in 
which it has been declared. 

label constant : synonymous with statement 
label. 

label prefix ; an unparenthesized identifi- 
er prefixed to a statement by a colon. 

leading zeros : zeros that have no signifi- 
cance in the value of an arithmetic number; 
all zeros to the left of the first signifi- 
cant digit (1 through 9) of a number* 

level number : an unsigned decimal integer 
constant specifying the hierachy of a name 
in a structure. It appears to the left of 
the name and is separated from it by a 
blank. 

level-one variable : a major structure 
name; any unsubecripted data variable not 
contained within a structure. 

list-directed transmission : the type of 
STREAM transmission in which data in the 
stream appears as constants separated by 
blanks or commas. 



3. the occurrence of an IF statement in a 
THEN clause or an ELSE clause. 

4. the occurrence of a function reference 
as an argument of another function 
reference. 

5. the occurrence of a subscript within a 
subscript. 

null locator value s a special locator 
value that cannot identify any location in 
storage; it gives a positive indication 
that a locator variable does not currently 
identify any allocation of a based 
variable. 



null string ; 
length. 



a string data item of zero 



numeric character data : arithmetic data 
described by a picture that is stored in 
character form. It has both an arithmetic 
value and a character- string value. The 
picture must not contain either an A or an 
X picture specification character. 

offset variable : a locator variable whose 
value identifies a location in storage, 
relative to the start of an area. 



list processing : the use of based 
variables and locator variables to build 
chains or lists of data. 



on- unit : the action to be executed upon 
the occurrence of the ON-condition named in 
the containing ON statement. 
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operator ; a symbol specifying an operation 
to be performed. See arithmetic operators , 

bit- string operators , comparison operators , 

and concatenation . 

option : a specification made in a state- 
ment that may be used by the user to 
influence the execution of the statement. 

packed decimal ; the System/3 60 internal 
representation of a fixed- point decimal 
data item. 

parameter : a name in an invoked procedure 
that is used to represent an argument 

passed to that procedure. 

parameter -at tribute list : a description in 
an ENTRY attribute specification that lists 
attributes of parameters of the named entry 
point. This enables dummy arguments to be 

created correctly - 

picture: a character- by- character specif i- 

catj >n describing the composition and 
attx^butes of numeric character and 

character-string data. It allows editing. 

point of invocation : the point in the 

invoking block at which the procedure 
reference to the invoked procedure appears. 



are encountered by the preprocessor (they 
appear without the percent sign in prepro- 
cessor procedures) . 

primary entry point : the entry point named 
in the PROCEDURE statement. 

problem data : string or arithmetic data 
that is processed by a PL/I program. 

procedure ; a block of statements, headed 
by a PROCEDURE statement and ended by an 
END statement, that defines a program 
region and delimits the scope of names and 
that is activated by a reference to its 
name. It controls allocation and freeing 
of automatic storage declared in that 
block. 



procedure reference : 
tine reference. 



a function or subrou- 



processor : the second of the two compiler 
stages. The stage at which the prepro- 
cessed text is compiled into an object 
module. 

program : a set of one or more external 
procedures, one of which must have the 
OPTIONS CHAIN) attribute in its PROCEDURE 
statement. 



pointer variable : a locator variable whose 
value identifies an absolute location in 
storage. 

precision : the value range of an arithme- 
tic variable expressed as the total number 

of digits allowed and, for fixed- point 
variables, the assumed location of the 

decimal Cor binary) point. 

prefix : a label or a parenthesized list of 
condition names connected by a colon to the 
beginning of a statement. 

prefix operator : an operator that pre- 
cedes , and is associated with, a single 
operand. The prefix operators are -j «• - 

preprocessed text : the output from the 
first stage of compile- time activity. This 
output is a sequence of characters that is 
altered source program text and which 
serves as input to the processor stage in 
which the actual compilation is performed. 

preprocessor : the first of the two compil- 
er stages. At this stage the source pro- 
gram is examined for preprocessor state- 
ments which are then executed, resulting in 
the alteration of the source program text. 

preprocessor statements : special state- 
ments appearing in the source program that 
specify how the source program text is to 
be altered i they are identified by a lead- 
ing percent sign and are executed as they 



program control data : data used in a PL/I 
program to affect the execution of the pro- 
gram. Program control data consists of the 
following types: label, event, task, 
pointer, offset, and area. 

prologue : those processes that occur at 

the activation of a block. 

pseudo-variable : one of the built-in func- 
tion names that can be used as a receiving 
field. 

pushed-down stack : a stack of allocations 
to which new allocations are added and 
removed from the top on a last-in, first- 
out basis. 

qualified name : a sequence of names of 
structure members connected by periods, to 
uniquely identify a component of a struc- 
ture. Any of the names may be subscripted. 

receiving field : any field to which a 
value may be assigned. 

record: the unit of transmission in a 
RECORD input or output operation; in the 
internal form of a level-one variable* 

recorded key : a character string recorded 
in a direct-access volume to identify the 

data record that immediately follows. 

recursion s the reactivation of a procedure 
while it is already active. 
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repetition factor : a parenthesized 
unsigned deciiral integer constant preceding 
a string configuration as a shorthand 
representation of a string constant. The 
repetition factor specifies the number of 
occurrences that make up the actual con- 
stant. In picture specifications, the 
repetition factor specifies repetition of a 
single picture character. 

repetitive specification : an element of a 
data list that specifies controlled itera- 
tion to transmit a list of data items, gen- 
erally used in conjunction with arrays. 

returned value : the value returned by a 
function procedure to the point of 
invocation. 

scale : fixed- or floating-point represen- 
tation of an arithmetic value. 



static storage : storage that is allocated 
before execution of the program begins and 
that remains allocated for the duration of 

the program. 



stream : data being transferred frosr. or to 
an external medium represented as a con- 
tinuous string of data items in character 

form. 



string : a connected sequence of characters 
or bits that is treated as a single data 

item. 



structure : a hierarchical set of names 
that refers to an aggregate of data items 
that may or may not have different 
attributes . 



scope (of a condition prefix) : the range 
of a program throughout which a condition 
prefix applies. 

scope (of a name) : the range of a program 
throughout which a name has a particular 
interpretation . 



subf ield : the integer description portion 
or the fraction description portion of a 
picture specification field that describes 
a noninteger fixed- point data item. The 
subfields are divided by the picture char- 
acter V. 



secondary entry point : an entry point 
defined by a label of an ENTRY statement 
within a procedure- ' 

source key : a character string referred to 
in a RECORD transmission statement that 
identifies a particular record within a 
direct-access data set. The source key may 
or may not also contain, as its first part, 
a substring to be compared with, or written 
as, a recorded key to positively identify 
the record. Note: The source key can be 
identical to the recorded key. 

source program : the program that serves as 
input to the compiler. The source program 
may contain preprocessor statements. 

standard file : a file assumed by the com- 
piler in the absence of a FILE or STRING 
option in a GET or PUT statement (the stan- 
dard files are: SYSIN for input, SYSPRINT 
for output) . 

statement : a basic element of a PL/I pro- 
gram that is used to delimit a portion of 
the program, to describe data used in the 
program, or to specify action to be taken. 

statement label : an identifying name pre- 
fixed to any statement other than a PROCE- 
DURE or ENTRY statement. 

statement label variable : a /ariable 
declared with the LABIAL attribute and thus 
able to assume as its value a statement 
label. 



subroutine s a procedure that is invoked by 
a CALL statement or a CALL option. A sub- 
routine cannot return a value to the invok- 
ing block, but it can alter the value of 
variables that are known within the invok- 
ing block. 



subscript : an element expression specify- 
ing a location within a dimension of an 
array. A subscript can also be an 
asterisk, in which case it specifies the 
entire extent of the dimension. 

synchronous : describes serial execution of 
a progranr, using a single flow of control. 

termination of block : cessation of execu- 
tion of a block, and the return of control 
to the activating block by means of a 
RETURN or END statement, or the transfer of 
control to the activating block or some 
other active block by means of a GO TO 
statement. A return of control to the 
operating system via a RETURN or END state- 
irent in the initial procedure or a STOP or 
EXIT statement in any block results in the 
termination of the program. See epi logue . 

variable : a name that represents data. 
Its attributes remain constant, but it can 
represent different values at different 
times. Variables fall into three cate- 
gories: element, array, and structure 
variables. Variables may be subscripted 
and/or qualified. 
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data mapping 316 
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pointer 129,14 8 
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structure 128 
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preprocessor 157 
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examples of 215 

length of result 217 
arithmetic built-in functions 226,220 
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conversion 212,30 
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arithmetic conversion 210,30 
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scale in 216,43 
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arithmetic data 13 

attributes for 256 
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defaults for 253 
arithmetic operations 31 
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errors to avoid 174-176 
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adjustable 139 
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multiple 50,285-286 
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preprocessor 310 

types of 284 
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in DECLARE statements 288 

default 68 # 72 

(see also default) 
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errors to avoid 171-173 
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file 72 
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listing of 6,69 
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specification of 256 
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AUTOMATIC attribute 260,52 
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automatic variables 27 
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BACKWARDS option 299 
base 13,31 
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decimal 13 
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Index 337 



BASED attribute 260,138-139 
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in recursive procedure 64 
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termination of 6 
BEGIN statement 287,12 
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BINARY built-in function 227 
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bit-string data 
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bit-string format item (B) 204,89 
bit-string operations 34 
bit-string operators 9 
bit-string targets 45,221 

bit-string to arithmetic conversion 214,30 
bit- string to character-string 

conversion 214,30 
blank picture character CB) 196,114 
balnks 10 

in constants 211,19,20 

in data-directed transmission 85 

in keys 106 

in list-directed transmission 83,79 

in numeric character data 196 

in picture specifications 114 



101-102 
93,94 



in preprocessor replacement 154,158 

in structure declarations 25 

use of 10 
BLKSIZE subparameter 93,102 
block size 94,93, 102 
block structure 1,166 
blocking of records 93,101-102,71 

alignment 326-328 

record-oriented transmission 

stream-oriented transmission 
blocks 56, 5 

activation of 58-59 

begin 56,1 

invocation of 59 

multiple closure of 57-58 

nested 57 

procedure 56,1 

record 71,93,101-102 

in stream-oriented transmission 79 

and structures, external 70 

on tape 71-72 

termination of 60 
EOOL built-in function 221,117 
boolean operation 221,117 
bounds 22,236 

in ALLOCATE statement 281-282 

asterisk notation for 127 

expressions for 127 

of array parameters 127 
branch 52-53 

(see also GC TO statement) 
BSI pence characters 201 
ESI shilling characters 201 
BUF <see BUFFERED attribute) 
buffer 

alignment 326-328 

and based storage 62 
BUFFERED attribute 262,73 

EVENT option 289 
BUFFERED option 299 
buffering attributes 73 
buffers 73,97 

allocation of 94 # 102 

hidden 73,261 
EUFFERS option 94,102 
BUFNO subparameter 94,102 
built-in functions 220,41 

arithmetic 226-232,220 

array manipulation 236,220 

as arguments 129 

based storage 239-240 

computational 221,220 

condition 237,134 

mathematical 232-236,220 

miscellaneous 240- 241, 220 

multitasking 240 

string-handling 221, 117 

values returned by 122 
EUILTIN attribute 262,122 
BY clause 82,290,291 
EY NAME option 283,39,284,285 

in array assignment 285 

in structure assignment 40,284-285 



C format item 205,89 
CALL option 271,27 
CALL statement 287,54 
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multitasking 7,55 
calling trace 299 
card punch codes 185-186 
carriage control 91,103 
CEIL built-in function 227 , 217 

data mapping 317,318 
ceiling values 217 
chaining technique 150 
CHAJR built-in function 222 , 117 
CHAR48 compiler option 186 
CHARACTER attribute 261,19 

in ^DECLARE statement 154,155,310,311 

in ^PROCEDURE statement 158,313 

in ALLOCATE statement 281 

data mapping 317,318 
character sets 185-186,8 
character-class data 264 
character- string comparison 35 
character-string data 18-20 

as keys 98,106 

assignment of 19,284 

attributes for 19,261 

comparison of 35 

concatenation of 36 

constants 9,18 

conversion of 211,221 

defined on numeric character data 113 

picture specification for 192,115 

variables 19,261 
character-string format item (A) 204,88-89 
character-string targets 45,212 
character- string to arithmetic 

conversion 211,30 
character- string to bit- string 

conversion 214,30 
character- string value of numeric 

character 193,113 
characters 8 
CHECK condition 251,136 

raised for null statement 297 

standard system action for 136, 254 
CHECK condition prefix (see CHECK prefix) 
CHECK prefix 135-136,252 
classes 

of statements 48 

of storage 61,6 
clauses 

BY 82,290,291 

ELSE 53,296-297 

THEN 53,296 

TO 82,292 

WHILE 54,82,292 
CLOSE statement 288,50 

unlocking of record 304 
closing of files 77,50 

multiple 77,288 
closure, multiple 57-58 
COBOL option 10 3 

codes for ON- conditions (see condition* 
codes) f 

collating sequence 117,222,223,35 r X 
collections of data 

arrays 7,22-23 

arrays of structures 25 

structures 23-25 
COLUMN format item 205,80,90 
comma picture character C f ) 196,114 
commas 



in data-directed transmission 79 

in list-directed transmission 79,83 

in parameter attribute lists 124 
comments 10,160 
common logarithm 235 
comparison 34-35,9 

of keys 106 
COMPLETION built-in function 240 
completion value of event variable 240,242 
COMPLEX attribute 262,14 

with PICTURE attribute 262,276,277 
COMPLEX built-in function 227 
complex data 16-17,14 

attributes for 17,256 

picture specification for 277 
COMPLEX format item CO 205,89 
complex numeric character data 276,277,212 
COMPLEX pseudo- variable 242 
complex to character-string conversion 214 
complex value 227-228,229 
composite symbols 185-186 
compound statements 11 
computational built-in functions 218 

arithmetic 2 26 

array manipulation 236-237 

mathematical 232-2 36 

string-handling 221 
computational conditions 247 
computational statements 50 
concatenation 35-36,31 
condition built-in functions 237,134 
condition codes 245,134 
CONDITION condition 255,133 

with SIGNAL statement 307 
condition name 244,11 

use of NO with 131 
condition prefix 244,7 

effect on nested blocks 131-132 

scope of 131,244 
conditional branch 53 
conditional digit position 195 
conditional insertion characters 196 
conditions 231-24 2,55 

codes for 244,245,134 

computational 247 

disabled 244,299 

enabled 244,298-299 

exceptional 131,7 

input/output 249, 247 

program checkout 251,247 

raised in conversions 46 

•system action 247 

user-named 255 
CONJG built-in function 228 
conjugate of complex value 228 
CONSECUTIVE option 104,92,101 

alignment 328 

compared with SEQUENTIAL attribute 104 

EVENT attribute 267 

EVENT option 98 

NCP option 104 
CONSECUTIVE organization 94,102-104 

compared with INDEXED 
organization 105-106 
constants 13 

arithmetic 14 

attributes of 13 

bit-string 20, 30 



Index 339 



blanks in 211 
character-string 18-19, 10 
label 20 
sterling 15 
contained in, meaning of 65 
contextual declaration 66-67 
of built-in function 

identifiers 122-123 
of entry names 126 
of event names 267 
of user-named condition 255 
control 

flow of 58-64 
return of 60,247 
control format items 90 
control statements 52-55 

control variable in DO statement 53,291 
controlled 

arguments 127 
parameters 126-127 
storage 62*6 

allocation of 281 
freeing of 294 
stacking of 62 
variables 6 2,63,27 

bounds and lengths for 
CONTROLLED attribute 259 f 62 
conversion 41-42,6 

arithmetic 43-45,210 
base in '43,44,211 
mode in 31,43,210 
precision in 4 3,4 4,211 
scale in 4 3,210 
target attributes in 42-45 
arithmetic to bit-string 214,43,45 
arithmetic to 

character-string 212,43,45 
in arithmetic operations 31 
in array expressions 37 
by assignment 31,50 
base 31,43 

bit-string to arithmetic 214,45 
bit-string to character-string 214,42 
in bit-string operations 34 
character-string to arithmetic 211,43 
character- string to bit-string 214,42 
coded arithmetic to 

character-string 212,43 
coded arithmetic to numeric 

character 211 
in comparison operations 34 
complex to character- string 214 
conditions raised in 46-47 
efficiency of 164-166,168 
in exponentiation operations 33 
inline 164-166 
intermediate results in 42 
numeric character to coded 

arithmetic 211,43 
offset to pointer 31 
pointer to offset 31 
in preprocessor expressions 156 
type 211 
CONVERSION condition 248,46-47 
in assignment to picture 245 
in B-format input 205 

for character-string to arithmetic 30 
for character-string to bit-string 214 



in E- format input 2 06 

null on-onit for 133 

ONCHAR used for 237 

ONSOURCE used for 239 

in STREAM input 203 
COPY option 80,295-296 
correspondence defining 262,263 
COS built-in function 234 
COSD built-in function 234 
COSH built-in function 234 
COUNT built-in function 241 
CR picture characters 202 
credit picture characters (CR) 197 
cross sections of arrays 23 
CTLASA option 103 
CTL360 option 103 
currency symbol picture character 
($) 196,114 



data 

aggregates 176-177 
(see also array) 

area 144-145,23 

arithmetic 13 

comparison of 35 
conversion of 212,43,44-45 

attributes of 256,69 
(see also attributes) 

bit-string 20 

comparison of 3 5 
concatenation of 35 
conversion of 4 2 
operations with 34 

character-string 18-19 
comparison of 3 5 
concatenation of 36 
conversion of 211,42 

collections of 7,21-22 

conversion of 41-47,30-37 

editing of 110-112 

event 21 

format items 203,87-89 
examples of 89 

implicit conversion 164,165 

inline conversion 164-166 

item 79 

label 20 

locator 21 

movement of 50-51 

offset 144-145,21 

pointer 21 

problem 13,30 

program control 20,30 

string 18-20 

task 21 

typed 49 

types of 5,13,120 
data interchange 93,101-102 
EATA keyword 80,84-86 
data list 81-82 

element of 83 

omission of 84-85 
data management routines 93,101 
data mapping 315-328 
data sets 79 

COBOL-generated 10 3 

files, association with 76 
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organization of 102-106,94 

positioning of 94-95,103 

in stream- oriented transmission 79 
data specification 81-91,114 

data-directed 85-87 

edit- directed 87-91 

list-directed 8 3-85 
data transmission 71,96 

Csee also input /out put) 

statements 

(see also DELETE statement; GET 
statement? LOCATE statement; PUT 
statement; READ statement; REWRITE 
statement; UNLOCK statement; WRITE 
statement) 
record-oriented transmission 96-97 
stream-oriented transmission 80-91 
data-directed transmission 79 

data specification for 85-87 

input 8 5 

CHECK condition for 251,134 

output 8 6 
DATAFIELD built-in function 238 
DATE built-in function 241 
DB picture characters 197 
DCB parameter 93,10 2 
DDEF command 92-94,101-104,76-77 

BLKSIZE suboperand 93 

BUFNO suboperand 94 

DCB suboperands 9 3 

DISP operand 94 

KEYLEN suboperand 106 

LRECL suboperand 93 

RECFM suboperand 9 3 

for record-oriented 
transmission 101-104,106 

RKP suboperand 106 

for standard file 78 

for stream-oriented transmission 93 
ddname 76,77 

in %INCLUDE statement 312 
deactivation 155, 310 

(see also termination) 

of preprocessor entry names 157 

of preprocessor variables 156 
debit picture characters (DB) 199 
debugging 134,55 
debugging file 132 
decimal, packed 15 
DECIMAL attribute 261,14 

data mapping 317,318 
decimal base 13 
DECIMAL built-in function 228 
decimal data 14-16,277 
decimal point picture character 

(V) 194,114 
declarations 65-70 

errors to avoid 171-173 
DECLARE statement 288,48 

condition prefix to 132 

preprocessor 311,155-160 

RETURNS attribute 121 
default 6,68 

for arithmetic data 262,269 

attributes assumed by 1^.,256 

for attributes of value returned by 
function 121 

conditions enabled by 244,136 



for file attributes 73 

for preprocessor variables 155 
DEFINED attribute 263,25-26 

evaluation of 264 
defined item 262-264 
defining 263 
DELAY statement 289 
DELETE statement 289,49 

unlocking of record 304 
density of tape 72 
descriptive statements 48 
device independence 71 

digit specifier picture characters 194,276 
digits 8 

DIM built-in function 236 
dimension 22,265 

bounds of 22,2 36 

extent of 22,236 

maximum number of 23,38,39,57 
dimension attribute 265,22 

in ALLOCATE statement 281 
DIRECT attribute 266,73 

comparison with SEQUENTIAL 
attribute 105-106 ,108-109 
direct-access storage devices 93,101 
disabled conditions 131,244 

compared to null on-unit 132 
DISP operand of DDEF command 104 
DISPLAY statement 290, 50 
DIVIDE built-in function 228 
division operations 33 

attributes of results of 219 

remainder of 229 
division operator 31 

in preprocessor expressions 156 
DO-group 57,11 

errors to avoid 176-177 

preprocessor 159,311 

transfer of control into 292,296 
DO keyword in repetitive specification 82 
DO- loop (see DO-group) 
DO statement 290-292,11,53-54 

blocks , nesting of 57 

condition prefix to 131 

iterative 53-54 

noniterative 54 

preprocessor 311 

types of 290-291 
drifting picture characters 197-198 
drifting string 197,198 
DSNAME parameter 76 t 77 
dumray arguments 123-124,136 

attributes 124 
dump, obtained by CHECK prefix 134 
dynamic storage allocation 61 f 6 



E format item 206,89 

I picture character 200,276 

EBCDIC (Extended Binary Coded Decimal 

Interchange Code) 185-186,35 
EDIT keyword 87-91,80 
edit-directed transmission 80,111 
data specification for 87-91 
format items for 203 r 88-89 
FORMAT statement for 294 
input 87 
output 87 
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editing 

by assignment 110-117 , 50 

of numeric character data 192 

by PICTURE attribute 112 
efficient performance 161-180 
element 

and array operations 38 f 37 

assignment 28 3 

of data list 83 

expression 29 , 236 

in array assignment 285 
in IF statement 53,296 

of structure 23 

and structure operations 39 

variable 22 
ELSE clause 

in % IF statement 160,312 

in IF statement 53,35 
embedded key 10 6 

EMPTY built-in function 239,146 
enabled condition 131-134,244 
end of file 85 
END statement 29 2-293,12 

tor begin block termination 60 

u locks, nesting of 5 7 

multiple closure by 57-58 

preprocessor 311 

for procedure termination 60 f 119 
ENDFILE condition 249,98 
ENDPAGE condition 249,91-92 
ENTRY attribute 266,51 

in %DECLARE statement 158,311 

compared with ENTRY statement 51 

contextual declaration of 266 

in generic entry name declaration 270 

implied 121,125 
entry name 58,121 

as argument 125-126,129 

attributes for 257 

in CALL statement 287 

contextual declaration of 66,125,266 

explicit declaration of 300,125 

parameters 126,129 

preprocessor 156-157 
entry point 118,266 

primary 58,300 

secondary 58,293 
ENTRY statement 293,51,58 

compared with ENTRY attribute 51 

condition prefix to 132 

label of 65,125 

parameters of 293 
ENVIRONMENT attribute 92-95,101-109 

general format 74 

for record-oriented 
transmission 101-109 

for stream-oriented transmission 92-95 
epilogues 6 4 

ERF built-in function 234 
ERFC built-in function 234 
ERROR condition 255,131-136 
AREA condition 254 
raised by GET statement 295 

raised by PUT statement 302 
results in program termination 61 
errors to avoid in programming 170-180 
established action 132,133 
EVENT attribute 267,21 



data mapping 316 
event data 21 
event name 267 

(see also event variable) 
EVENT option 98,66 

and CHECK condition 136 

in DELETE statement 289 

in BEAD statement 303 

in REWRITE statement 306 

in WRITE statement 309 
event variable 98,246 

active 251,306 

completion value of 242,240 

inactive 251,306 
exception control statements 55,48 
exceptional conditions 131,7 
EXCL (see EXCLUSIVE attribute) 
EXCLUSIVE attribute 268,74 
execution speed 166-170 
EXIT statement 293,55 
EXP built-in function 234 
explicit declaration 65-66 

by DECLARE statement 288 
explicit opening 74-75 
exponent 

of floating-point data 15 

in picture specification 200,276 
exponent field 200 

exponent specifier picture characters 200 
exponentiation operations 33-34,31,32 

attributes of result 219 

base 43 

conversion 31,32 

mcde 43 

precision 43 

scale 43 
expressions 29-47,6 

array 37-39,29 

for array bounds 167,265 

attributes of result of 6,32 

for controlled parameters 127 

element 29 

in format items 91 

function reference operands 40-41 

operands of 40-41 

operational 29 

preprocessor 156,309 

in RETURN statement 120 

for string lengths 167 

structure 39-40,29 

as subscripts 23 

use of parentheses in 37 
extended binary coded decimal interchange 

code (see ep-CDIC) 
extent 

of area 144 

ot dimension 22,236 

in overlay defining 264 
EXTERNAL attribute 269,61 

CHECK condition 
external declaration 257 
external names 10,68 

structures 70 
external procedure 57,1 
external storage 71 
external structure 70 

external text, compile- time incorporation 
of 159,312 
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F format item 207 f 88-91 

F picture character 201 

F-format (fixed-length) records 93,102 

factor 27,28 

factoring of attributes 256 f 288 

in %DECLARE statement 311 
family members 271 
field 

in picture specification 193,275 

width 20 3 
file 72 

association with data set 76,49 

attributes for 72-74 r 257 

closing of 74,288 

contextual declaration of 74 

name of (see file name) 

opening of 74-75,299 

standard 77-78,92 
FILE attribute 269,72,73 
file declarations, examples of 109 
file name 72,97 

arguments 129 

length of 76 

parameters 129 

in stream-oriented transmission 79 
FILE option 97,49,80 

of GET statement 2 95 

of PUT statement 301-302 
FILE specification 

of CLOSE statement 288 

of DELETE statement 289 

of OPEN statement 299 

of READ statement 303 

of REWRITE statement 306 

of WRITE statement 308 
FINISH condition 255,61 
FIXED attribute 269,14 

in ^DECLARE statement 310-311 

in %PROCEDURE statement 158,313 

data mapping 317,318 

with preprocessor variables 155 
FIXED built-in function 228 
fixed-length records (F-format) 93,101,102 

(see also format-F records) 
fixed-point data 14-15 

assignment of 14 

binary 15,23 

constants 14-17 

conversion of 212-213 

decimal 14-15 

division operations with 33 

picture specification for 194,276 

sterling 15 

variables 14-17,23 
fixed-point format item(F) 207,88-91 
fixed-point scale 13 
FIXEDOVERFLOW condition 248,46 

compared with SIZE condition 47 

disabling 163 
FLOAT attribute 269,16 

data mapping 317,318 
FLOAT built-in function 228 
floating-point data 15-16 

binary 16 

constants 15,16 

conversion of 210,213 

decimal 15-16 

long form of 16,210 



picture specification for 200,276 

short form of 16,210 

variables 16 
floating-point format item (E) 206,88-91 
floating-point scale 13 
FLOOR built-in function 229 
flow of control 58-64,52 
flow trace 134 
format-F record 

alignment 328 

record-oriented transmission 102 

stream-oriented 
transmission 9 3,94,10 3,104 
format, record 92-94,101-102 
format items 88-91 

alphabetic list of 204 

control 90,87,88 

data 203,87-90 

remote 204, 87, 88,90 

spacing 204 

summary of 88 
format list 88,203 

in FORMAT statement 294 
FORMAT statement 294 
format-U record 

recc rd-oriented transmission 102 

stream-oriented transmission 93,94 
forraat-V record 

alignment 326-328 

record-oriented transmission 10 2 

stream-oriented transmission 93,94 
format-VB record 326 
fractional digits 206,207 
fractional subfields 194 
free format 8 
FREE statement 294-295,6 
freeing of based storage 143-144 
freeing of controlled storage 52,294 
FROM option 97,109,308 
FROM specification (see FROM option) 
fullword, binary 15 
function 120-130, 41 

(see also built-in functions) 

arguments of 118-119,123-139 

built-in 220,41 

errors to avoid 177 

name of 123 

preprocessor 313 

references (see function references) 

termination of 120 

value returned by 120,305 

without arguments 121 
function file attributes 73 
function references 120,40 

preprocessor 156-157 



G sterling picture character 201 
gap, interblock 72 
gap, interrecord 72 
generation 

of data 281 

stack of generations 127 

of variable 259 
GENERIC attribute 269-270,129 
generic name 129,269,270 
generic reference 129 
GENKEY option 108 
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GET statement 295,49,75,78 

for internal data movement 50 
NAME condition raised by 250 
with standard input file 78 
stream-oriented transmission 80 
with STRING option 50-51,295 

GO TO statement 296,52-53 

for begin block termination 60 

label variable in 52-53 

in on- unit 132 

for procedure termination 60,119,120 



H sterling picture character 201 
ha If word 15 

11BOUND built-in function 237 
hxdden buffers 73,262 

hierarchy of names 23 
HIGH built-in function 222,117 
high- order digits, loss of 32 
(see also SIZE condition) 



I picture character 2 00 

identical structuring, meaning of 39 

identifiers 9,15,16 

built-in function 122,123 

eompile-time replacement of 140 

length of 9 

reserved 122 
IF statement 29 6,11 

condition prefix to 131 

element expression in 53,296 

nested 297 

preprocessor 312 
IGNORE option 109 
ignoring of records 112-113 
1MAG built-in function 229 
IMAG pseudo-variable 242 
imaginary number 263 

imaginary part of complex value 213,228 
implementation information 2 
implication, file attributes derived by 79 
implicit declaration 67-69 
implicit freeing of based storage 143 
implicit opening 109 

uNDEFINEDFILE raised in 251 
implied attributes 109 
IN option 142,145 
inactive event variable 251,306 
inactive identifier 310 
included text 159,312 

effect on preprocessor scan 159 

preprocessor procedures in 160 
INDEX built-in function 222-223,117 
INDEXED data set 104-109,94,254 

alignment 350 

comparison with CONSECUTIVE data 
set 105-106 
infix operations 30,32 
infix operators 31 

array expressions with 37-38 

structure expressions with 39 
INITIAL attribute 271,27 

in ALLOCATE statement 281-283 
for label variables 271-272 
initial key 106 
initial procedure 59,255 



(see also main procedure) 
initialization 27-28, 271-272 

of automatic variables 27 

of controlled variables 27,283 

errors to avoid 173-174 

of label arrays 271-272 

of static variables 27,62 
inline operations 164-166 
input 6-7,71 

standard system file for 78 
INPUT attribute 273,73-77 
INPUT option 299 
input/output 

of based variables 141 

conditions 249-252,131 

errors to avoid 177-180 

event 246,308 

locate-mode 139, 151 

record-oriented 78,6,7 
statements for 96,49 

statements 48-49,71 

stream-oriented 79,6,7 

conversion in 111 

data-directed 85-86, 49 

edit-directed 88-8 9,49 

list-directed 83-84, 49 

statements for 80,49 
insertion picture characters 196,115 
integer subfield 193 
interblock gap 72 
interleaved array 224 
interleaved subscripts 25,86 
intermediate results 42 
intermediate string 213 

maximum length 110 
internal procedure 57 
INTERNAL attribute 269,68-70 

structure members 70 
internal to, meaning of 65 
interrecord gap 7 2 
interruption 7,55 

established action for 134 

investigation of 238 

multiple 246 

ORDER option 162 

relaxation of rules 161,162 

REORDER option 162,161 

simulation of 55 

specification 326 

synchronous 99 
intervening blank 19, 20 
INTO option 97,111 
invocation 

CALL statement for 287-288 

procedure 59 

preprocessor procedure 156,157 
invoked procedure 59-60 
IRREDUCIBLE attribute 273 
iSUB variables 26,263,264 
iteration factor 27-28 

compared with repetition factor 28 

in format list 88 

in INITIAL attribute 27,271 
iterative execution 290-292 

(see also repetitive execution) 
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K picture character 276,115,200 
KEY condition 250,106 
KEY option 9 8 

in DELETE statement 289 

error 106 

in READ statement 303 

in REWRITE statement 306 
KEYED attribute 273,74-76 

example 109 
KEYED option 299 
KEYFROM option 98 

error 106 
KEYLEN suboperand of DDEF command 106 
keys 106,74 

comparison 106 

conversion of 46 

length of 10 6,46 

in READ statement 303 

recorded 106 

source 106 
KEYTO option 98 

error 106 
keyword statements 10 
keywords 9-10,187-191 



label 

argument 129,121 

constants 20 

data 20 

parameter 118 

prefix 11 

of preprocessor statement 157 

statement label 65 

variable 273-274 

in GO TO statement 52-53 
initialization of 272 
LABEL attribute 273-274,257 

data mapping 316 

INITIAL attribute 271 
layout of pages 91-92 
LBOUND built-in function 237 
leading blanks in the stream 203 
leading zeros 86,156 
LEAVE option 94,103 
length 

of area 144 

in arithmetic to bit-string 
conversion 217 

in arithmetic to character-string 
conversion 217 

of bit- string targets 45 

of character-string targets 45 

of external names 10,68 

of fields 87,84 

of file names 81 

of identifiers 10 

of keys 106,46 

maximum for strings 19,20 

minimum for strings 19,20 

of record blocks 94,102 

of recorded key 106 

specified in ALLOCATE statement 281-282 

of string parameters 127 

of strings 118,18 

of tape 72 
length attribute 26 2,19,20 
LENGTH built-in function 223,19 



level numbers 24 

in DECLARE statement 288 

factoring of 256 

in LIKE attribute specification 274 

logical level, not same as 315 

maximum permitted 24 

for structure parameters 128 
level- 1 variables 96,288 

in READ statement 303 

in REWRITE statement 30 6 

in WRITE statement 308 
LIKE attribute 274,26 

INITIAL attribute 271 
line of data 79 
LINE format item 208,249 
LINE option 301-302,80,236-237 
line position format item (see LINE format 

item) 
line size for PRINT file 94 
line skipping format item (see SKIP format 

item) 
LINENO built-in function 241 
IINESIZE option 91-92,299 
LIST keyword 83-84,80 
list-directed data specification 83 
list-directed output 83 
list-directed transmission 79,83 
list processing 138,150 
list processing condition 254-255,247 

(see also AREA condition) 
list of program variables (see data list) 
locate mode input/output 139,151 

alignment 326-328 

data mapping 315,326-328 

record alignment 326-328 
LOCATE statement 297,49 

alignment 326-238 

and based variable 62 

OUTPUT attribute 273 

pointer setting by 141 

RECORD attribute 279 
locator arguments and parameters 148 
locator conversion 31 
locator data 21,31 

locator returns from entry points 148 
locator variables 149 
locking records 307,50 

(see also EXCLUSIVE attribute) 
LOG built-in function 234-235 
logarithms 234-235 
logical level 315 
logical operations, errors to 

avoid 174-176 
logical records 71,72 

on tape 72 
LOG10 built-in function 235 
LOG2 built-in function 235 
long floating-point form 16 
loop optimization 163 
LOW built-in function 223,117 
lower bound 22,237 
LRECL sutparameter 102 



14 sterling picture character 201 
machine independence 5, 1 
magnetic tape 71-73,93,101 
MAIN option 300 
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main procedure 54,59 
major structure 

alignment 140 

name 23,2 5 

offset to 140 

pointer to 140 
mantissa 200 f 206 

in picture specification 276,198 
mapping of data 315-328 

mathematical built-in functions 232-236 
MAX built-in function 229 
maximum length 

bit-string data 20 

character- string data 19 

CHECK name 253 

fixed-point data 248 

identifiers 9 

intermediate string result 110 

LABEL list 27 3 

LINESIZE option 299 

numeric-character picture 
specification 194 

parameter list 314 

picture specification 20,194 

sterling fixed-point data 15 

STRING result 224 

string variable 110 

VARYING string 36 
maximum number of binary digits 15 
maximum number of decimal digits 14 
maximum precisions 278,14-16,44 
member of external structure 70 
merging of attributes 75-76 
MIN built-in function 229 
minor structure 

alignment 140 

name 23, 25 

offset to 140 

pointer to 140 
minus sign picture character (-) 197,199 
miscellaneous built-in functions 240,220 
MOD built-in function 229 
MOD data-set disposition 104 
mode 14 

in arithmetic conversion 30-31,43-44 

of arithmetic targets 43 

of arithmetic variables 263 

complex 16,14 

conversion of 31,210 

in exponentiation 43-44 

of numeric character data 276 

real 14 
Model 44 Programming System 93,101-102 
modes of stream transmission 49,79 
modularity 1,5 
multiple assignment 50,284 
multiple closing of files 77 
multiple closure 57-58 

by %END statement 312 

of blocks 57-58 

of DO- groups 57 

by END statement 57-58 

of preprocessor DO-groups 159 
multiple declarations 70 
multiple interruptions 246,238 
multiple opening of files 75 
multiplication 33,218 
MULTIPLY built-in function 230 



multiprogramming 21 
multitasking 7, 21, 55, 280 
multitasking built-in functions 240 



NAME condition 250,84,85 

name list of CHECK condition 252 

names 9,65-70 

attributes for 256-280,5 

in CHECK condition prefix 134 

condition names 11,55 

entry names 58 

event names 267 

external names 10, 68 

file names 97 

generic names 129 

hierarchy of 23 

procedure names 51, 56 

qualification of 24-25 

qualified names 24-25,83 
subscripted 25 

scope of 65-68 

of structure members, external 70 

structure names 23-25 

subscripted names 23,25,86 

unique names 70 
natural logarithm 234 
NCP option 103,104,189 
nested blocks 57,70 
nested function 4 2 
nested IF statements 297 
nested repetitive specifications 82 
nesting 5 

of XIF statements 160,312 

of ^INCLUDE statements 313 

in array expression 38 

of blocks 57,70 

effect of condition prefix with 132 

ENTRY attribute 267,271 

of factored attributes 256 

of preprocessor DO-groups 159 

in structure expression 39 
NO with condition names 11,132 
NOCHECK 2 44 
NOCONVERSION 244 
NOFIXEDOVERFIOW 244 
NOLOCK option 99 
noniterative DO statements 54 
nonsequential access 108, 109 
NOOVERFLCW 244 
normal return 247 
normal termination 54,60-61 

of on-unit 247 

of procedure 60 

of program 61 
normalized hexadecimal floating-point 16 
NOSlZE 244 
NOSUBSCRIPTRANGE 244 
"not* operation 34 
NOUNDERFLOW 244 
NOZERODIVIDE 244 
null bit-string constant 20 
NULL built-in function 240,143 
null character-string constant 19 
null ELSE clause in %IF statement 160 
null offset value 146,240 
null on-unit 132-133 
null pointer value 143,240 
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null statement 297 f 10 
as on-unit 132-133 

null string 

character string 19 

conversion to arithmetic 211 

result in arithmetic to bit-string 217 

NULLO built-in function 240,146 

numeric character data 17-18, 112-115 f 275 
arithmetic value of 113 , 275 
character-string value of 113 
compared with coded arithmetic data 17 
conversion in arithmetic operations 17 
conversion to character-string 212 
conversion to coded arithmetic 17,211 
format 17 

picture characters for 193 
picture specification for 112-115 
signs in 197 

numeric character picture 
specifications 193-19**, 112-113 

numeric character variables 192 

numeric picture specifications 17 



object program 153 
offset arguments 148,129 
OFFSET attribute 275,145 

data mapping 316 
offset data 145-146,21 
offset parameters 148-149 
offset returns from entry points 148,149 
offset to pointer conversion 31 
offset variables 138 

defining 147 

examples of use 151 

null values of 146,240 

restriction 140 

setting value of 146 
ON statement 297-299,11 

condition prefix to 131 

purpose of 132 

scope of 133 

SNAP option of 132 
ON-codes (see condition codes) 
ON-conditions 244-245,132-137 

errors to avoid 177 

example of use 134-137 
ON-unit 132,98-99 

begin block as 132 

errors to avoid 177 

return of control from 132,247 

speed of execution slowed by 166 
ONCHAR built-in function 238,242 
ONCHAR pseudo-variable 242,66 
ONCODE built-in function 238,134 
ONCOUNT built-in function 238 
ONFILE built-in function 238 
ONKEY built-in function 239 
ONLOC built-in function 239 
ONSOURCE built-in function 239,242 
ONSOURCE pseudo-variable 242,66 
OPEN statement 299,74-77 

as descriptive statement 48 

format of 76 

as input/output control statement 49 

options of 299,72 
opening files 74-77,49,299 

attributes, specification of 72-73 



explicit openings 74-75 

implicit openings 75,109 

multiple openings 75 
operands 29-41 

of array expressions 37-38 

of bit-string operations 34 

of comparison operations 35 

of concatenation operations 35 

element 38,39 

in expression evaluation 42 

of expressions 40-41 

function reference 40-41 

of preprocessor expressions 156 

of structure expressions 39,40 
Operating System 93,101 
operational expressions 29-31 
operations 

arithmetic 31-34 

errors to avoid 169 

array 38 

bit-string 34,30 

combinations of 36-37 

comparison 34-35 

concatenation 35-36 

element 38,39 

four classes of 31 

infix 30 

logical 174-176 

prefix 30 

structure 39,40 
operators 9 

concatenation 35 

in expression evaluation 42 

infix 31 

array expressions with 38 
structure expressions with 39 

prefix 31 

array expressions with 38 
structure expressions with 39 

priority of 36-37 
OPT compiler option 163 
optimization of program 161-180 
OPTIONS option 300 

OPTIONS (MAIN) specification 300,12,59 
"or" operation 34 

order of evaluation of expressions 36 
ORDER option 161-162,189 

BEGIN statement 287 

PROCEDURE statement 300,301 
organization of data set 102-106,74,94 
output 71-109,6-7 

(also see input/output) 
OUTPUT attribute 273,73 

for standard file 78 
output files 96,109 

standard system output file 77-78,92 
OUTPUT option 299 
OVERFLOW condition 248,11,34 
overlay defining 264-265,258,259,117 
cverpunched sign picture 
characters 199-2 00 



P format item 208,88-90,112 
P sterling picture character 
packed decimal format 14 
padding of keys 106,303 
PAGE format item 208,90 
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SYSPRINT 91,92 
page layout 91-92 
PAGE option 30 2 , 8 
PAGESIZE option 91-92 

default for 249,300 
paging format item (PAGE) 208,203 
pairing 315-326 

parameter attribute lists 124 f 128 
parameter lists 118,65 

variable length 149 
parameters 118-119, 69 

in ^PROCEDURE statement 313 

area 148 

array 128 

attributes of 118 f 119 f 126 

bounds and lengths of 127 

controlled 127 

in DDEF command 76-77,92-94,101-104 

default attributes for 267,120 

element 128 

entry name 129 

explicit declaration of 120 

file name 129 

label 121 

offset 148,129 

pointer 147-14 8,129 

of preprocessor functions 157-158,313 

of primary entry point 300 

of secondary entry point 293 

simple 127,265 

storage allocation for 126-127 

string 129 

structure 128 
parenthsses 124 , 37 

level of 42 

number permitted 57 
pence character specifier (P) 201 
pence digit specifiers (7 and 8) 201 
pence field 202,193 
PENDING condition 191 
percent symbol 139,141 
physical organization of data set 74 
physical record 71,72 
physical sequential data sets (see PS data 

sets) 
PICTURE attribute 275,112 

with COMPLEX attribute 263 

data mapping 317,318 
picture characters 112-115,275-278 

for character-string data 192 

for numeric character data 193 
picture format item (P) 208 
picture specification 275-276 

for character-string data 217,115 

for editing 112 

inline conversion 164-166 

for numeric character 
data 193-194 , 112-11 5 
PLI command 186 

(see also CHAR4 8 compiler option? OPT 
compiler option; SORMGIN compiler 
option) 
plus sign picture character 

(*) 197,114-115 
point alignment in numeric character 

data 113-114,197 
point insertion picture character (•> 197 
point of invocation 59 



pointer arguments 147-148,129 
pointer assignment 142 
POINTER attribute 275,66 

data mapping 316 
pointer data 21 
pointer parameters 147 
pointer qualification 140,64 
pointer returns from entry points 148 
pointer to offset conversion 31 
pointer variables 139,140 

contextual declaration of 66 

defining 140 

examples of use 150 

null value of 143,240 

restrictions 139-140 

setting value of 142 

stacking of 64 

storage class 64 
POLY built-in function 237 
"Popped-up" stack 260,281 
"Popped-up" storage 62 
POSITION attribute 26 4,26 
positioning of data sets 94-95,103 
positioning of records 109 
pounds field 202,193 
precision 13-17,30 

of arithmetic constants 18 

in arithmetic conversion 44-45 

attribute 278 

in conversion 30,43-45,210 

default 278,14 

default for preprocessor variables 156 

in exponentiation 43 

function, value returned by 120 

and length specifications 44,45 

maximum 278,14-16,44 

of numeric character data 276 

of source 210 

of sterling data 277-278 

of subscripts 23 

of target 210,43-45 
PRECISION built-in function 230 
Prefix list 131 
Prefix operations 30 
Prefix operators 31 

array expressions with 37-38 

structure expressions with 39 
prefixes 11 

condition 244,11 

label 11 
preprocessed text 154,157 
preprocessor 7 

DO-groups 159,311 

expressions 156 

in %IF statement 312 
arithmetic operators in 156 
evaluation of 156,310 
operands of 156 
in RETURN statement 157,314 

function reference 158 

functions 157-159,313 

input to 153 

output from 153 

procedure name 156,314 
establishment of 311 
in included text 159 
invocation of 156 
scope of 311 
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scan 153 

control of sequence of 154,311 

stage 153 

statement s 309,153 

abbreviation of keywords 187-191 
comments in 160 
labels of 160 

variable 155-156,310 

maximum precision 155 
primary entry point 58-59,300 
PRINT attribute 279,91-92 
PRINT files 80 

block size 94 

column positioning 205 

format items for 80 

line positioning 208 

page layout 91-92 

record format 94 

record size 94 
PRINT option 299 
printing format items 203,80 
priority 

of operators 36-38 

of types in comparison operations 35 
PRIORITY built-in function 240 
PRIORITY CPL/I built-in function, and 

pseudo-variable) option 7 
PRIORITY pseudo/variable 242 
problem data 13-20,30 

attributes for 256 
procedure 56,5 

communication between procedures 51 

END statement for 292 

external 57,1 

function 120-123, 51 

initial 59,255 

internal 57 

invocation of 287,59 

main 54,59 

nesting of procedures 119 

preprocessor 156 

subroutine 119 
procedure block (see procedure) 
procedure name 51,56 
procedure reference 58 
PROCEDURE statement 300,12 

blocks, nesting of 57 

condition prefix to 131 

CHECK condition prefix 252,134 

label of 65,126 

ORDER option 161,162 

REORDER option 161,162 
procedure termination 60-61 
processor stage 153 
PROD built-in function 237 
program 

blocks 56,11-12 

calling 58-59,63 

checkout 131,135 

checkout conditions 252,132 

control 171 

control data 13,20-21 
attributes for 257 

debugging 247 

entry point of 266 

interruption 11, 50,244 

optimizing 161-180 

segmentation 166 



structure statements 51-52,48 

termination 61 

testing of 131 
prologues 64 
PS (physical sequential) data sets 

record-oriented transmission 101-102 

stream-oriented transmission 9 3 
pseudo-variables 241, 41 

in expression evaluation 4 2 

errors to avoid 177 
"Pushed-down* environment 63 
"Pushed-down" stack 6 2,260 
"Pushed-down" storage 281,64 
PUT statement 301,50,80 

ENDPAGE condition raised by 249 

for internal data movement 50 

with standard files 78 

stream-oriented transmission 80 

with STRING option 50 



qualification by pointer 139 
(also see based storage) 

qualified names 24-25,83 
in LIKE attribute 274 
subscripted 25 

quotation marks in stream 203 



R format item 208-209,90 
R picture character 199-200 
random access 108,109 
READ statement 303,96 

alignment of record 326 

and based variable 6 2 

pointer setting by 141 

purpose of 4 9 

record alignment 326 

SET option 141-142,140 
REAL attribute 263,14 
REAL built-in function 230 
real mode 14 
real number 263 

real part of complex number 16,17 
REAL pseudo-variable 242 
receiving field 241,41 
RECFW subparameter 93,102 
RECORD attribute 279,73 
record blocks 71-72 
RECORD condition 249,99 

raised by READ statement 303 

raised by REWRITE statement 306 

raised by WRITE statement 308 
record format 92-94,101-104 

F 92,93,102 

options 92,101 

record-oriented transmission 101-102 

stream-oriented transmission 93,94 

U 92-94,102-104 

V 92-94,102-104 
RECORD option 299 
record positioning 109 
record size 93,102 

RECORD condition raised by 250 

in stream-oriented transmission 79 
record-oriented transmission 96-109,71-72 

attributes for 72 

characteristics of 96,71 
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data mapping 315 

statements 96 , 48-49 
options of 97 
summary of 108 
recorded keys 106,98,108,109 
records 7 

(see also record format) 

addition of 94,103 

alignment 326-328 

blocked 93,101 

boundaries 7 9 

deletion of 103 

format of 92-94,101-102 

format-F 92,93,102 

format-U 92,102 

format~V 92,93,102 

locking and unlocking of 109 

(also see EXCLUSIVE attribute) 

logical 71,72 

physical 71 

replacement of 77,94,103 

rereading of 77 

retrieval of 94,103 

self-defii ing 140 

on tape 71-72 

unblocked 72,93,102 
recursion 6^-64 

effect on storage class 63-64,260 

i i remote format items 208-209 
RECURSIVE option 300,63 
recursive procedure 62-64 
REDUCIBLE attribute 273 
REFER option 13 9,140 

alignment 349 

R3AD with SET, effect on 142 
ref e cences 

a nbiguous 70,24 

f Jnction 120,40-41 

generic 129 

s ibroutine 119 
REGI )NAL option 191 

a T.ignment 32 8 
relacive structuring 131 
remote format item (R) 208-209,90 
REORDER option 161-162,190,287 

PROCEDURE statement 300,301 
REPEAT built-in function 223,117 
repetition factor 19 

in bit-string constants 20 

in character-string constants 19,28 

compared with iteration factor 28 

in INITIAL attribute 271,28 

in preprocessor expressions 156 
repetitive execution 290,53-54 
repetitive specification 82 
replacement 310 

of identifiers 154 

by preprocessor function value 158 

replacing records 77 
replacement value 154,155 
REPLY option 290,50 
rereading records 77 
reserved identifier 10,65 
results 

of arithmetic operations 32-34 

of array operations 37-38 

attributes of 32-36 

of bit-string operations 34 



of comparison operations 34-35 

of concatenation operations 35-36 

of element operations 38 

intermediate 4 2 

of structure operations 39-40 
return of control from 

function 121 

invoked procedure 6 

on-unit 60,247 

subroutine 119 
RETURN statement 305,54 

expression in 120 

for function termination 120 

preprocessor 314,156 
expression in 158 

for subroutine termination 120 
returned value 30 5 

of arithmetic built-in function 226 

of array manipulation built-in 
function 236 

attributes of 121, 293 

conversion of 121 

for preprocessor function 158 

default attributes for 280 

of mathematical built-in 
function 232-233 

of preprocessor function 158 

of preprocessor procedure 311 

of string-handling built-in 
function 221 
RETURNS attribute 279,121-122,190 

in DECLARE statement 311,157,158 
RETURNS option 121 

^PROCEDURE statement 158,313 

ENTRY statement 293 

example 305 

RETURNS attribute 279 
REVERT statement 305,50 
REWRITE statement 306,96 

purpose of 49 

unlocking of record 304 
RKP suboperand 106 

alignment 326-328 
RKP suboperand of DDEF command 106 
ROUND built-in function 230 
row-major order 8 3 



S picture character 199,198 
scalar expression 29 
scalar variable 21 
scale 13 

in arithmetic conversion 32,43 

of arithmetic targets 43,44 

conversion of 32 

in exponentiation 43 

of numeric character data item 276 
scale factor 278 

range permitted 27 8 
scaling factor 89,212 

in F format item 207 

in picture specification 276 
scaling factor picture character 

(F) 200-201 
scan by preprocessor 153 
scope 66-67 

attributes for 269,257 

of condition prefix 244,131 
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of declaration 65-67 

of member names of external 
structures 70 

of name 256,65-68 

of ON statement 132 

of preprocessor variable 155 

of structure member 70 
secondary entry point 58 # 293 
self-defining data 140 
semicolon 79 f 85 

ne-character set 186 
SEQ1 (see SEQUENTIAL attribute) 
SEQI ENTIAL attribute 266,72-76 

< Dmpared with CONSECUTIVE option 104 

i. ompared with DIRECT 
attribute 105-106,108-109 

EVENT attribute 267 

and EVENT option 98 f 289 

and NCP option 104 
SET option 97,142 

alignment of record 326 

and based variable 62 

record alignment 326 

relationship to REFER option 142 

self-defining data 140 
shillings field 202,193 
short floating-point form 16, 210 
sign, determination of 231 
SIGN built-in function 231 
sign picture characters 197,276 
SIGNAL statement 307,133 

AREA condition 254-255 
significant digits 206, 211 

(see also SIZE condition) 
simple parameters 127,265 
simple statement 10-11 
simulation of an interruption 55 
SIN built-in function 235 
SIND built-in function 235 
SINH built-in function 235 
SIZE condition 248,11,46 

in base conversion 211 

compared with FIXEDOVERFLOW 
condition 47 

disabling 163, 171, 172 

in E format output 206 

in F format output 207 

MOD function 230 

in precision conversion 211 
size of area 144 
SKIP format item 209,203 
SKIP option 301,80 
skipping of records 97,109 
slash picture character (/) 196-197,114 
SNAP option 299,132 
SORiMGIN compiler option 170 
source data item 42 
source keys 106,98 
source program 153 
spacing format item (X) 209,90 
special characters 8,9 
specification interruption 326 
speed of execution 166-170 
SQFT built-in function 235 
stacking of controlled storage 62 
stacking of pointer variables 64 
stacks 259,281 
standard files 77-78,92 



system output CSYSIN) 294 

system output (SYSOUT) 80 
standard system action 244-255,55,131,132 

for CHECK condition 134 
statement label constants 273 
statement label designators 204,208 
statement label variable 21 
statement labels 11,65 
statements 281 

classes of 48 

compound 10,11 

keyword 10 

null 10 

preprocessor 309,160 

simple 10,11 
static allocation 61 
STATIC attribute 260,61 
static picture characters 197,199 
static storage 61-62 
static variables 27,52 

allocation of 61 

initialization of 27,62 
STATUS built-in function 240 
STATUS pseudo-variable 242 
sterling fixed-point data 15,278 
sterling picture specifications 201,193 

examples of 201 
STMT compiler option 166 
STOP statement 307,55 
storage 

allocation 61-62 ,5 , 6 
attributes for 260 
dynamic 6,61 

effect of recursion on 63-64 
for parameters 126-127 

classes of (see storage classes) 

external 71 

freeing of 259, 260 

popped-up 62 

pushed-down 62 
storage classes 6,61-62 

attributes for 61,52 

automatic 6,52 

based 138-147,6 

controlled 6,52 

of pointer variables 64 

static 6,52 
storage devices, direct-access 93,101 
stream 203 

STREAM attribute 72-75,279,280 
STREAM option 299 
stream-oriented transmission 79-95 

attributes for 72 

characteristics of 79,71 

conversion in 79,71 

data mapping 315 

modes 79,80 

statements 80-83 ,49 

uses for 49 
string 

arguments 132 

assignment 272 

based 139 

fixed-length 262 ,115 

operators 9 

parameters 129 

varying-length 110, 223, 224, 262 
string data 18-20,13 
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attributes for 262,257 

errors to avoid 177 

inline conversion 164,165 

length of (see string length) 
string-handling built-in functions 221,220 

inline handling 166 
string length 118,18 

adjustable 139 

determination of 221 

expressions for 167 

REFER option 139,141 

varying 223-224, 110, 262 
STRING option 111,50-51 

in GET statement 50-51,295 

in PUT statement 50-51,302 
STRING pi eudo- variable 242-243,117,190,221 
STRINGRANGE condition 254,136 

(also see SUBSTR built-in function) 
string to arithmetic conversion 43 
structure 139,140 

arguments 128 

assignment 284,285 

declarations, blanks used with 24 

operations 4 

parameters 128 
structure, block 1 
structure expressions 29,39-40 

dimensions in 57 

in structure assignment 284 
structure level r maximum permitted 24 
structure mapping 315-326 
structure names 24,25 

external 70 
structure variables 274,23-24 

in LIKE attribute specification 257 
structures 23-25 

arrays cf 25 

COBOL 103 
structuring 

identical 39,274 

LIKE attribute 26,274 

relative 128 
subfield delimiter 194 
subfields in a picture 

specification 193,275 
subroutine 119,5 
subroutine reference 119 
subscripted names 23,25,86 
subscripted qualified names 25 
subscripted variable 42 
SUBSCRIPTRANGE condition 254,134,136 
subscripts 22-23 

in arguments 128 

asterisks as 23 

checking of 134 

evaluation of 254 

in expressions 38,39 

expressions as 23 

interleaved 25,86 

internal form of 23 

optimization 163 

precision of 23 
SUBSTR built-in function 224,41 

in preprocessor expressions 156,158-159 

third argument 36 
SUBSTR pseudo-variable 243 

in assignment statement 286 
substring 117,224 



subtraction 32-33, 218 
SUM built-in function 237 
synchronous interruptions 99 
syntactic unit 183 
syntax errors to avoid 17-171 
SYSIN 77-78,92 
SYSULIB 313 

SYSPRINT/SYSOUT 77-78 , 92 
as debugging file 132 
system action 244-245,55,131,132 
system action conditions 255,247 
system action specification 50,132 



T picture character 200 

tab positions 80,86 

TAN built-in function 235 

TAND built-in function 235-236 

TANK built-in function 236 

tape (see magnetic tape) 

tape density 72 

target 41 

base of arithmetic target 43 

length of bit-string target 45 

length of character-string target 45 

mode of arithmetic target 43-44 

precision of arithmetic target 44,210 

scale of arithmetic target 44 
target attributes 42-45 
task 7 

data 21 

variables 21 
TASK attribute 316,191 
TASK option 7,191 
temporary result 

in assignment statement evaluation 42 

in conversions 41,4 2 

in DO statement evaluation 291 

in expression evaluation 42 
termination 

abnormal 55-293 

of blocks 58-59 

of function 120 

normal 54,60-61 

of on-unit 132,98-99,247 

of procedure 60-61 

of subroutine 119 
testing of program 131 
THEN clause 

in %IF statement 312,160 

in IF statement 296,53 
three-line skip 92 
TIME built-in function 241 
TITLE option 299,76,77 
TO clause 291 
TR machine instruction 225 
track overflow PI/I option 104 
transfer of control by GO TO statement 296 
TRANSIENT attribute 72,96,191 
TRANSLATE built-in 

function 224-225 , 117 ,191 , 220 
transmission statements 

(see DELETE statement; GET statement; 
LOCATE statement; PUT statement; READ 
statement; REWRITE statement; UNLOCK 
statement; WRITE statement) 
TRANSMIT condition 251,98,99 

raised by DELETE statement 289 
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raised by READ statement 303 
raised by REWRITE statement 306 

raised by WRITE statement 309 
TRKOFL option 104 ,191 
TM* machine instruction 226 
TRUNC built-in function 231 
truncation 32,203 

in arithmetic operations 32 

of keys 303 

of source key 106 

in string assignment 110 
type 31 

type conversion 42-45,31 
typed data 4 9 



U-format records 92,102 
UNALIGNED attribute 140 

buffering 326 

data mapping 316,326 

GENERIC attribute 270 

string argument 224 
unblocked records 72,93,102 
unblocking 93,102 
UNBUFFERED attribute 262,73 

EVENT attribute 267 

and EVENT option 98 

and NCP option 104 
UNBUFFERED option 299 
unconditional branch 52-53 
unconditional insertion characters 196 
undefined format records 

(see U-format records) 
undefined- length records 

(see forroat-U records) 
UNDEFINEDFILE condition 251,75 

raised by implicit file opening 247,289 

raised for TRANSIENT files 72 
UNDERFLOW condition 248,244 
UNLOCK statement 307,50 
unlocking records 109 

(also see EXCLUSIVE attribute) 
UNSPEC built-in function 225,117 
UNSPEC pseudo-variable 243 
UPDATE attribute 280,73 
UPDATE option 299 
upper bound 22, 237 
usage file attributes 73 



V picture character 194,113 
variable 13 

array 22,81 

automatic 27 

and based storage 62 

control 53-54 

controlled 27,52 

element 21,22,96 

event 98,246 

iSUB 26 

label 20,21 

pseudo- variables 41 

scalar 21 



statement-label 20 

static 27,52 

structure 23-24,274 
variable-length records 

(see format-V records) 
VARYING attribute 262,36 

with bit-strings 20 

with character-strings 19 

READ statement 303 

REWRITE statement 306 

WRITE statement 309 
VARYING strings 110 
varying-length records (see V-format 

records) 
VERIFY built-in function 226,117,191,220 
virtual access method (VAM) 93,101 
VAM (virtual access method) 
virtual storage data sets 

record-oriented transmission 101-102 
virtual storage data sets 

stream-oriented transmission 93 
volume 71 



WAIT statement 307,66 
WHILE clause 291,54 
work area in PL/I 62 
WRITE statement 308,75 

alignment of record 326 

purpose 49 

record alignment 326 



X format item 209,90,91 

X picture character 192,115 



Y picture character 195,115 

Z picture character 195,113 
zero suppression 194,113 

in data- directed transmission 79-80 

in E format output 206 

in edit-directed transmission 88 

in F format output 207 

in list-directed transmission 79 

in numeric character data 113 

picture characters for 194 

in sterling pictures 202 
ZERODIVIDE condition 249,244 
zeros, extensions with 110 
zoned decimal format 17 



48-character set 8,186 

6 sterling picture character 201 
60-character set 8,185 

codes for 185 

7 sterling picture character 201 

8 sterling picture character 201 

9 picture character 194,113,115 
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